diff --git a/package.json b/package.json index d761ba18..21fa9f74 100644 --- a/package.json +++ b/package.json @@ -64,9 +64,9 @@ }, "dependencies": { "@jsonjoy.com/base64": "^1.1.2", - "@jsonjoy.com/buffers": "^1.0.0", + "@jsonjoy.com/buffers": "^1.2.0", "@jsonjoy.com/codegen": "^1.0.0", - "@jsonjoy.com/json-pointer": "^1.0.1", + "@jsonjoy.com/json-pointer": "^1.0.2", "@jsonjoy.com/util": "^1.9.0", "hyperdyperid": "^1.2.0", "thingies": "^2.5.0" diff --git a/src/rm/README.md b/src/rm/README.md new file mode 100644 index 00000000..d0af7b54 --- /dev/null +++ b/src/rm/README.md @@ -0,0 +1,37 @@ +# Record Marking (RM) Protocol + +Implements rm/tcp/ip protocol Record Marking (RM) Standard as specified in RFC 1057. +The RM standard splits a byte stream into discrete messages by prefixing each +message with a 4-byte header. + +Excerpt from RFC 1057, Section 10: + +``` +10. RECORD MARKING STANDARD + + When RPC messages are passed on top of a byte stream transport + protocol (like TCP), it is necessary to delimit one message from + another in order to detect and possibly recover from protocol errors. + This is called record marking (RM). Sun uses this RM/TCP/IP + transport for passing RPC messages on TCP streams. One RPC message + fits into one RM record. + + A record is composed of one or more record fragments. A record + + + +Sun Microsystems [Page 18] + +RFC 1057 Remote Procedure Call, Version 2 June 1988 + + + fragment is a four-byte header followed by 0 to (2**31) - 1 bytes of + fragment data. The bytes encode an unsigned binary number; as with + XDR integers, the byte order is from highest to lowest. The number + encodes two values -- a boolean which indicates whether the fragment + is the last fragment of the record (bit value 1 implies the fragment + is the last fragment) and a 31-bit unsigned binary value which is the + length in bytes of the fragment's data. The boolean value is the + highest-order bit of the header; the length is the 31 low-order bits. + (Note that this record specification is NOT in XDR standard form!) +``` diff --git a/src/rm/RmRecordDecoder.ts b/src/rm/RmRecordDecoder.ts new file mode 100644 index 00000000..ade1835a --- /dev/null +++ b/src/rm/RmRecordDecoder.ts @@ -0,0 +1,49 @@ +import {StreamingReader} from '@jsonjoy.com/buffers/lib/StreamingReader'; +import {Reader} from '@jsonjoy.com/buffers/lib/Reader'; +import {concatList} from '@jsonjoy.com/buffers/lib/concat'; + +export class RmRecordDecoder { + public readonly reader = new StreamingReader(); + protected fragments: Uint8Array[] = []; + + public push(uint8: Uint8Array): void { + this.reader.push(uint8); + } + + /** + * @todo PERF: Make it return Slice instead of Uint8Array + */ + public readRecord(): Reader | undefined { + const reader = this.reader; + let size = reader.size(); + if (size < 4) return undefined; + const x = reader.x; + READ_FRAGMENT: { + try { + const header = reader.u32(); + size -= 4; + const fin = !!(header & 0b10000000_00000000_00000000_00000000); + const len = header & 0b01111111_11111111_11111111_11111111; + if (size < len) break READ_FRAGMENT; + reader.consume(); + const fragments = this.fragments; + if (fin) { + if (!fragments.length) return reader.cut(len); + fragments.push(reader.buf(len)); + const record = concatList(fragments); + this.fragments = []; + return record.length ? new Reader(record) : undefined; + } else { + fragments.push(reader.buf(len)); + return undefined; + } + } catch (err) { + reader.x = x; + if (err instanceof RangeError) return undefined; + else throw err; + } + } + reader.x = x; + return undefined; + } +} diff --git a/src/rm/RmRecordEncoder.ts b/src/rm/RmRecordEncoder.ts new file mode 100644 index 00000000..33a545f1 --- /dev/null +++ b/src/rm/RmRecordEncoder.ts @@ -0,0 +1,43 @@ +import {Writer} from '@jsonjoy.com/util/lib/buffers/Writer'; +import type {IWriter, IWriterGrowable} from '@jsonjoy.com/util/lib/buffers'; + +export class RmRecordEncoder { + constructor(public readonly writer: W = new Writer() as any) {} + + public encodeHdr(fin: 0 | 1, length: number): Uint8Array { + this.writeHdr(fin, length); + return this.writer.flush(); + } + + public encodeRecord(record: Uint8Array): Uint8Array { + this.writeRecord(record); + return this.writer.flush(); + } + + public writeHdr(fin: 0 | 1, length: number): void { + this.writer.u32((fin ? 0b10000000_00000000_00000000_00000000 : 0) + length); + } + + public writeRecord(record: Uint8Array): void { + const length = record.length; + if (length <= 2147483647) { + const writer = this.writer; + writer.u32(0b10000000_00000000_00000000_00000000 + length); + writer.buf(record, length); + return; + } + let offset = 0; + while (offset < length) { + const fragmentLength = Math.min(length - offset, 0x7fffffff); + const fin = fragmentLength + offset >= length ? 1 : 0; + this.writeFragment(record, offset, fragmentLength, fin); + offset += fragmentLength; + } + } + + public writeFragment(record: Uint8Array, offset: number, length: number, fin: 0 | 1): void { + this.writeHdr(fin, length); + const fragment = record.subarray(offset, offset + length); + this.writer.buf(fragment, length); + } +} diff --git a/src/rm/__tests__/RmRecordDecoder.spec.ts b/src/rm/__tests__/RmRecordDecoder.spec.ts new file mode 100644 index 00000000..f5dc57e7 --- /dev/null +++ b/src/rm/__tests__/RmRecordDecoder.spec.ts @@ -0,0 +1,131 @@ +import {RmRecordDecoder} from '../RmRecordDecoder'; + +describe('RmRecordDecoder', () => { + describe('.readRecord()', () => { + test('returns undefined when no data available', () => { + const decoder = new RmRecordDecoder(); + const result = decoder.readRecord(); + expect(result).toBeUndefined(); + }); + + test('decodes empty record', () => { + const decoder = new RmRecordDecoder(); + decoder.push(new Uint8Array([0, 0, 0, 0])); + expect(decoder.readRecord()).toBeUndefined(); + }); + + test('decodes empty record', () => { + const decoder = new RmRecordDecoder(); + decoder.push(new Uint8Array([0, 0, 0, 0, 0])); + expect(decoder.readRecord()).toBeUndefined(); + }); + + test('decodes empty record - 2', () => { + const decoder = new RmRecordDecoder(); + expect(decoder.readRecord()).toBeUndefined(); + decoder.push(new Uint8Array([0])); + expect(decoder.readRecord()).toBeUndefined(); + decoder.push(new Uint8Array([0])); + expect(decoder.readRecord()).toBeUndefined(); + decoder.push(new Uint8Array([0])); + expect(decoder.readRecord()).toBeUndefined(); + decoder.push(new Uint8Array([0])); + expect(decoder.readRecord()).toBeUndefined(); + }); + + test('decodes two records streamed one byte at a time', () => { + const decoder = new RmRecordDecoder(); + expect(decoder.readRecord()).toBeUndefined(); + decoder.push(new Uint8Array([0b10000000])); + expect(decoder.readRecord()).toBeUndefined(); + decoder.push(new Uint8Array([0])); + expect(decoder.readRecord()).toBeUndefined(); + decoder.push(new Uint8Array([0])); + expect(decoder.readRecord()).toBeUndefined(); + decoder.push(new Uint8Array([1])); + expect(decoder.readRecord()).toBeUndefined(); + decoder.push(new Uint8Array([42])); + expect(decoder.readRecord()?.buf()).toEqual(new Uint8Array([42])); + expect(decoder.readRecord()).toBeUndefined(); + decoder.push(new Uint8Array([0b10000000, 0, 0])); + expect(decoder.readRecord()).toBeUndefined(); + expect(decoder.readRecord()).toBeUndefined(); + decoder.push(new Uint8Array([1, 43])); + expect(decoder.readRecord()?.buf()).toEqual(new Uint8Array([43])); + expect(decoder.readRecord()).toBeUndefined(); + }); + + test('decodes single-byte record', () => { + const decoder = new RmRecordDecoder(); + decoder.push(new Uint8Array([0b10000000, 0, 0, 1, 42])); + const result = decoder.readRecord()?.buf(); + expect(result).toBeInstanceOf(Uint8Array); + expect(result!.length).toBe(1); + expect(result![0]).toBe(42); + }); + + test('decodes multi-byte record', () => { + const decoder = new RmRecordDecoder(); + const data = new Uint8Array([1, 2, 3, 4, 5]); + decoder.push(new Uint8Array([0b10000000, 0, 0, data.length, ...data])); + const result = decoder.readRecord()?.buf(); + expect(result).toBeInstanceOf(Uint8Array); + expect(result!.length).toBe(data.length); + expect(result).toEqual(data); + }); + + test('decodes ASCII string data', () => { + const text = 'hello world'; + const data = new TextEncoder().encode(text); + const decoder = new RmRecordDecoder(); + decoder.push(new Uint8Array([0b10000000, 0, 0, data.length, ...data])); + const result = decoder.readRecord()?.buf(); + expect(result).toBeInstanceOf(Uint8Array); + expect(result!.length).toBe(data.length); + expect(result).toEqual(data); + }); + + test('decodes large record', () => { + const size = 10000; + const data = new Uint8Array(size); + for (let i = 0; i < size; i++) data[i] = i % 256; + const decoder = new RmRecordDecoder(); + decoder.push(new Uint8Array([0b10000000, (size >> 16) & 0xff, (size >> 8) & 0xff, size & 0xff, ...data])); + const result = decoder.readRecord()?.buf(); + expect(result).toBeInstanceOf(Uint8Array); + expect(result!.length).toBe(data.length); + expect(result).toEqual(data); + }); + }); + + describe('fragmented records', () => { + test('decodes record with two fragments', () => { + const part1 = new Uint8Array([1, 2, 3]); + const part2 = new Uint8Array([4, 5, 6]); + const decoder = new RmRecordDecoder(); + decoder.push(new Uint8Array([0b00000000, 0, 0, part1.length, ...part1])); + expect(decoder.readRecord()).toBeUndefined(); + decoder.push(new Uint8Array([0b10000000, 0, 0, part2.length, ...part2])); + const result = decoder.readRecord()?.buf(); + expect(result).toBeInstanceOf(Uint8Array); + expect(result!.length).toBe(part1.length + part2.length); + expect(result).toEqual(new Uint8Array([...part1, ...part2])); + }); + + test('decodes record with three fragments', () => { + const part1 = new Uint8Array([1, 2]); + const part2 = new Uint8Array([3, 4]); + const part3 = new Uint8Array([5, 6]); + const decoder = new RmRecordDecoder(); + decoder.push(new Uint8Array([0b00000000, 0, 0, part1.length, ...part1])); + expect(decoder.readRecord()).toBeUndefined(); + decoder.push(new Uint8Array([0b00000000, 0, 0, part2.length, ...part2])); + expect(decoder.readRecord()).toBeUndefined(); + decoder.push(new Uint8Array([0b10000000, 0, 0, part3.length, ...part3])); + const result = decoder.readRecord()?.buf(); + expect(result).toBeInstanceOf(Uint8Array); + expect(result!.length).toBe(part1.length + part2.length + part3.length); + expect(result).toEqual(new Uint8Array([...part1, ...part2, ...part3])); + }); + }); +}); diff --git a/src/rm/__tests__/RmRecordEncoder.spec.ts b/src/rm/__tests__/RmRecordEncoder.spec.ts new file mode 100644 index 00000000..f28022d4 --- /dev/null +++ b/src/rm/__tests__/RmRecordEncoder.spec.ts @@ -0,0 +1,170 @@ +import {Writer} from '@jsonjoy.com/util/lib/buffers/Writer'; +import {RmRecordEncoder} from '../RmRecordEncoder'; + +describe('RmRecordEncoder', () => { + describe('.encodeHdr()', () => { + test('encodes header with fin=1 and length=0', () => { + const encoder = new RmRecordEncoder(new Writer()); + const result = encoder.encodeHdr(1, 0); + expect(result.length).toBe(4); + expect(result[0]).toBe(0x80); + expect(result[1]).toBe(0x00); + expect(result[2]).toBe(0x00); + expect(result[3]).toBe(0x00); + }); + + test('encodes header with fin=0 and length=0', () => { + const encoder = new RmRecordEncoder(new Writer()); + const result = encoder.encodeHdr(0, 0); + expect(result.length).toBe(4); + expect(result[0]).toBe(0x00); + expect(result[1]).toBe(0x00); + expect(result[2]).toBe(0x00); + expect(result[3]).toBe(0x00); + }); + + test('encodes header with fin=1 and length=100', () => { + const encoder = new RmRecordEncoder(new Writer()); + const result = encoder.encodeHdr(1, 100); + expect(result.length).toBe(4); + const view = new DataView(result.buffer, result.byteOffset, result.byteLength); + const value = view.getUint32(0, false); + expect(value & 0x80000000).not.toBe(0); + expect(value & 0x7fffffff).toBe(100); + }); + + test('encodes header with fin=0 and length=1000', () => { + const encoder = new RmRecordEncoder(new Writer()); + const result = encoder.encodeHdr(0, 1000); + expect(result.length).toBe(4); + const view = new DataView(result.buffer, result.byteOffset, result.byteLength); + const value = view.getUint32(0, false); + expect(value & 0x80000000).toBe(0); + expect(value & 0x7fffffff).toBe(1000); + }); + + test('encodes header with max length', () => { + const encoder = new RmRecordEncoder(new Writer()); + const maxLength = 0x7fffffff; + const result = encoder.encodeHdr(1, maxLength); + expect(result.length).toBe(4); + const view = new DataView(result.buffer, result.byteOffset, result.byteLength); + const value = view.getUint32(0, false); + expect(value & 0x80000000).not.toBe(0); + expect(value & 0x7fffffff).toBe(maxLength); + }); + }); + + describe('.encodeRecord()', () => { + test('encodes empty record', () => { + const encoder = new RmRecordEncoder(new Writer()); + const record = new Uint8Array([]); + const result = encoder.encodeRecord(record); + expect(result.length).toBe(4); + const view = new DataView(result.buffer, result.byteOffset, result.byteLength); + const header = view.getUint32(0, false); + expect(header & 0x80000000).not.toBe(0); + expect(header & 0x7fffffff).toBe(0); + }); + + test('encodes single-byte record', () => { + const record = new Uint8Array([0x42]); + const encoder = new RmRecordEncoder(new Writer()); + const result = encoder.encodeRecord(record); + expect(result.length).toBe(5); + const view = new DataView(result.buffer, result.byteOffset, result.byteLength); + const header = view.getUint32(0, false); + expect(header & 0x80000000).not.toBe(0); + expect(header & 0x7fffffff).toBe(1); + expect(result[4]).toBe(0x42); + }); + + test('encodes multi-byte record', () => { + const record = new Uint8Array([1, 2, 3, 4, 5]); + const encoder = new RmRecordEncoder(new Writer()); + const result = encoder.encodeRecord(record); + expect(result.length).toBe(9); + const view = new DataView(result.buffer, result.byteOffset, result.byteLength); + const header = view.getUint32(0, false); + expect(header & 0x80000000).not.toBe(0); + expect(header & 0x7fffffff).toBe(5); + expect(Array.from(result.slice(4))).toEqual([1, 2, 3, 4, 5]); + }); + + test('encodes record with ASCII data', () => { + const record = new TextEncoder().encode('hello'); + const encoder = new RmRecordEncoder(new Writer()); + const result = encoder.encodeRecord(record); + expect(result.length).toBe(9); + const view = new DataView(result.buffer, result.byteOffset, result.byteLength); + const header = view.getUint32(0, false); + expect(header & 0x80000000).not.toBe(0); + expect(header & 0x7fffffff).toBe(5); + expect(new TextDecoder().decode(result.slice(4))).toBe('hello'); + }); + + test('encodes large record', () => { + const size = 10000; + const record = new Uint8Array(size); + for (let i = 0; i < size; i++) record[i] = i % 256; + const encoder = new RmRecordEncoder(new Writer()); + const result = encoder.encodeRecord(record); + expect(result.length).toBe(4 + size); + const view = new DataView(result.buffer, result.byteOffset, result.byteLength); + const header = view.getUint32(0, false); + expect(header & 0x80000000).not.toBe(0); + expect(header & 0x7fffffff).toBe(size); + expect(Array.from(result.slice(4))).toEqual(Array.from(record)); + }); + }); + + describe('writeHdr', () => { + test('writes header without flushing', () => { + const encoder = new RmRecordEncoder(new Writer()); + encoder.writeHdr(1, 42); + encoder.writeHdr(0, 100); + const result = encoder.writer.flush(); + expect(result.length).toBe(8); + }); + }); + + describe('writeRecord', () => { + test('writes record without flushing', () => { + const encoder = new RmRecordEncoder(new Writer()); + const record1 = new Uint8Array([1, 2, 3]); + const record2 = new Uint8Array([4, 5]); + encoder.writeRecord(record1); + encoder.writeRecord(record2); + const result = encoder.writer.flush(); + expect(result.length).toBe(4 + 3 + 4 + 2); + }); + }); + + describe('.writeFragment()', () => { + test('writes fragment from offset', () => { + const encoder = new RmRecordEncoder(new Writer()); + const record = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); + encoder.writeFragment(record, 2, 3, 0); + const result = encoder.writer.flush(); + expect(result.length).toBe(7); + const view = new DataView(result.buffer, result.byteOffset, result.byteLength); + const header = view.getUint32(0, false); + expect(header & 0x80000000).toBe(0); + expect(header & 0x7fffffff).toBe(3); + expect(Array.from(result.slice(4))).toEqual([3, 4, 5]); + }); + + test('writes fragment with fin=1', () => { + const encoder = new RmRecordEncoder(new Writer()); + const record = new Uint8Array([10, 20, 30]); + encoder.writeFragment(record, 0, 3, 1); + const result = encoder.writer.flush(); + expect(result.length).toBe(7); + const view = new DataView(result.buffer, result.byteOffset, result.byteLength); + const header = view.getUint32(0, false); + expect(header & 0x80000000).not.toBe(0); + expect(header & 0x7fffffff).toBe(3); + expect(Array.from(result.slice(4))).toEqual([10, 20, 30]); + }); + }); +}); diff --git a/src/rm/index.ts b/src/rm/index.ts new file mode 100644 index 00000000..b85fd229 --- /dev/null +++ b/src/rm/index.ts @@ -0,0 +1,2 @@ +export * from './RmRecordDecoder'; +export * from './RmRecordEncoder'; diff --git a/src/rpc/README.md b/src/rpc/README.md new file mode 100644 index 00000000..379eac79 --- /dev/null +++ b/src/rpc/README.md @@ -0,0 +1,47 @@ +# RPC (Remote Procedure Call) Codec + +This codec implements streaming encoder and decoder for ONC (Open Network Computing) +RPC protocol. It supports all three major RPC RFCs: + +- **RFC 1057** (1988) - RPC: Remote Procedure Call, Version 2 +- **RFC 1831** (1995) - RPC: Remote Procedure Call Protocol Specification Version 2 +- **RFC 5531** (2009) - RPC: Remote Procedure Call Protocol Specification Version 2 (Internet Standard) + +See `RFC_COMPLIANCE.md` for detailed information about supported features and differences between RFC versions. + +## Note on Record Marking + +This RPC codec handles only the RPC message encoding/decoding as specified in +RFC 1057. It does NOT include Record Marking (RM) which is used to frame +messages over byte streams like TCP. + +For Record Marking support (as specified in RFC 1057 Section 10), use the +separate `rm` module. See `src/rm/README.md` for details. + +## Usage + +```typescript +import {RpcMessageEncoder, RpcMessageDecoder} from 'json-pack/rpc'; +import {RmRecordEncoder, RmRecordDecoder} from 'json-pack/rm'; + +// Encoding an RPC message +const encoder = new RpcMessageEncoder(); +const rpcMessage = encoder.encodeCall(xid, prog, vers, proc, cred, verf); + +// For TCP transport, wrap with Record Marking +const rmEncoder = new RmRecordEncoder(); +const framedMessage = rmEncoder.encodeRecord(rpcMessage); + +// Decoding +const rmDecoder = new RmRecordDecoder(); +const rpcDecoder = new RpcMessageDecoder(); + +// First extract the record from the byte stream (returns Reader) +rmDecoder.push(tcpData); +const record = rmDecoder.readRecord(); + +// Then decode the RPC message from the Reader +if (record) { + const message = rpcDecoder.decodeMessage(record); +} +``` diff --git a/src/rpc/RpcMessageDecoder.ts b/src/rpc/RpcMessageDecoder.ts new file mode 100644 index 00000000..b28ed47f --- /dev/null +++ b/src/rpc/RpcMessageDecoder.ts @@ -0,0 +1,92 @@ +import {Reader} from '@jsonjoy.com/buffers/lib/Reader'; +import {RpcMsgType, RpcReplyStat, RpcAcceptStat, RpcRejectStat} from './constants'; +import {RpcDecodingError} from './errors'; +import { + RpcOpaqueAuth, + RpcCallMessage, + RpcAcceptedReplyMessage, + RpcRejectedReplyMessage, + RpcMessage, + RpcMismatchInfo, +} from './messages'; + +export class RpcMessageDecoder { + public decodeMessage(reader: Reader): RpcMessage | undefined { + const startPos = reader.x; + try { + if (reader.size() < 8) return undefined; + const xid = reader.u32(); + const msgType = reader.u32(); + if (msgType === RpcMsgType.CALL) { + if (reader.size() < 20) return (reader.x = startPos), undefined; + const rpcvers = reader.u32(); + // if (rpcvers !== RPC_VERSION) throw new RpcDecodingError(`Unsupported RPC version: ${rpcvers}`); + const prog = reader.u32(); + const vers = reader.u32(); + const proc = reader.u32(); + const cred = this.readOpaqueAuth(reader); + if (!cred) return (reader.x = startPos), undefined; + const verf = this.readOpaqueAuth(reader); + if (!verf) return (reader.x = startPos), undefined; + const params = reader.size() > 0 ? reader.cut(reader.size()) : undefined; + return new RpcCallMessage(xid, rpcvers, prog, vers, proc, cred, verf, params); + } else if (msgType === RpcMsgType.REPLY) { + if (reader.size() < 4) return (reader.x = startPos), undefined; + const replyStat = reader.u32(); + if (replyStat === RpcReplyStat.MSG_ACCEPTED) { + const verf = this.readOpaqueAuth(reader); + if (!verf || reader.size() < 4) return (reader.x = startPos), undefined; + const acceptStat = reader.u32(); + let mismatchInfo: RpcMismatchInfo | undefined; + if (acceptStat === RpcAcceptStat.PROG_MISMATCH) { + if (reader.size() < 8) return (reader.x = startPos), undefined; + const low = reader.u32(); + const high = reader.u32(); + mismatchInfo = new RpcMismatchInfo(low, high); + } + const results = reader.size() > 0 ? reader.cut(reader.size()) : undefined; + return new RpcAcceptedReplyMessage(xid, verf, acceptStat, mismatchInfo, results); + } else if (replyStat === RpcReplyStat.MSG_DENIED) { + if (reader.size() < 4) return (reader.x = startPos), undefined; + const rejectStat = reader.u32(); + let mismatchInfo: RpcMismatchInfo | undefined; + let authStat: number | undefined; + if (rejectStat === RpcRejectStat.RPC_MISMATCH) { + if (reader.size() < 8) return (reader.x = startPos), undefined; + const low = reader.u32(); + const high = reader.u32(); + mismatchInfo = new RpcMismatchInfo(low, high); + if (!mismatchInfo) return (reader.x = startPos), undefined; + } else if (rejectStat === RpcRejectStat.AUTH_ERROR) { + if (reader.size() < 4) return (reader.x = startPos), undefined; + authStat = reader.u32(); + } + return new RpcRejectedReplyMessage(xid, rejectStat, mismatchInfo, authStat); + } else { + throw new RpcDecodingError('Invalid reply_stat'); + } + } else { + throw new RpcDecodingError('Invalid msg_type'); + } + } catch (err) { + if (err instanceof RangeError) { + reader.x = startPos; + return undefined; + } + throw err; + } + } + + private readOpaqueAuth(reader: Reader): RpcOpaqueAuth | undefined { + if (reader.size() < 8) return undefined; + const flavor = reader.u32(); + const length = reader.u32(); + if (length > 400) throw new RpcDecodingError('Auth body too large'); + const paddedLength = (length + 3) & ~3; + if (reader.size() < paddedLength) return undefined; + const body = length > 0 ? reader.cut(length) : new Reader(new Uint8Array(0)); + const padding = paddedLength - length; + if (padding > 0) reader.skip(padding); + return new RpcOpaqueAuth(flavor, body); + } +} diff --git a/src/rpc/RpcMessageEncoder.ts b/src/rpc/RpcMessageEncoder.ts new file mode 100644 index 00000000..e41a80b1 --- /dev/null +++ b/src/rpc/RpcMessageEncoder.ts @@ -0,0 +1,185 @@ +import {Writer} from '@jsonjoy.com/util/lib/buffers/Writer'; +import {Reader} from '@jsonjoy.com/buffers/lib/Reader'; +import {RpcMsgType, RpcReplyStat, RPC_VERSION} from './constants'; +import {RpcEncodingError} from './errors'; +import {RpcOpaqueAuth, RpcCallMessage, RpcAcceptedReplyMessage, RpcRejectedReplyMessage, RpcMessage} from './messages'; +import type {IWriter, IWriterGrowable} from '@jsonjoy.com/util/lib/buffers'; + +export class RpcMessageEncoder { + constructor(public readonly writer: W = new Writer() as any) {} + + public encodeCall( + xid: number, + prog: number, + vers: number, + proc: number, + cred: RpcOpaqueAuth, + verf: RpcOpaqueAuth, + params?: Reader | Uint8Array, + ): Uint8Array { + this.writeCall(xid, prog, vers, proc, cred, verf, params); + return this.writer.flush(); + } + + public encodeAcceptedReply( + xid: number, + verf: RpcOpaqueAuth, + acceptStat: number, + mismatchInfo?: {low: number; high: number}, + results?: Reader | Uint8Array, + ): Uint8Array { + this.writeAcceptedReply(xid, verf, acceptStat, mismatchInfo, results); + return this.writer.flush(); + } + + public encodeRejectedReply( + xid: number, + rejectStat: number, + mismatchInfo?: {low: number; high: number}, + authStat?: number, + ): Uint8Array { + this.writeRejectedReply(xid, rejectStat, mismatchInfo, authStat); + return this.writer.flush(); + } + + public encodeMessage(msg: RpcMessage): Uint8Array { + this.writeMessage(msg); + return this.writer.flush(); + } + + public writeMessage(msg: RpcMessage): void { + if (msg instanceof RpcCallMessage) { + this.writeCall(msg.xid, msg.prog, msg.vers, msg.proc, msg.cred, msg.verf, msg.params); + } else if (msg instanceof RpcAcceptedReplyMessage) { + this.writeAcceptedReply(msg.xid, msg.verf, msg.stat, msg.mismatchInfo, msg.results); + } else if (msg instanceof RpcRejectedReplyMessage) { + this.writeRejectedReply(msg.xid, msg.stat, msg.mismatchInfo, msg.authStat); + } + } + + public writeCall( + xid: number, + prog: number, + vers: number, + proc: number, + cred: RpcOpaqueAuth, + verf: RpcOpaqueAuth, + params?: Reader | Uint8Array, + ): void { + const writer = this.writer; + writer.ensureCapacity(16 * 4); + const view = writer.view; + let x = writer.x; + view.setUint32(x, xid, false); + x += 4; + view.setUint32(x, RpcMsgType.CALL, false); + x += 4; + view.setUint32(x, RPC_VERSION, false); + x += 4; + view.setUint32(x, prog, false); + x += 4; + view.setUint32(x, vers, false); + x += 4; + view.setUint32(x, proc, false); + x += 4; + writer.x = x; + this.writeOpaqueAuth(cred); + this.writeOpaqueAuth(verf); + if (params instanceof Uint8Array) { + if (params.length > 0) writer.buf(params, params.length); + } else if (params instanceof Reader) { + const size = params.size(); + if (size > 0) writer.buf(params.subarray(0, size), size); + } + } + + public writeAcceptedReply( + xid: number, + verf: RpcOpaqueAuth, + acceptStat: number, + mismatchInfo?: {low: number; high: number}, + results?: Reader | Uint8Array, + ): void { + const writer = this.writer; + writer.ensureCapacity(16 * 4); + const view = writer.view; + let x = writer.x; + view.setUint32(x, xid, false); + x += 4; + view.setUint32(x, RpcMsgType.REPLY, false); + x += 4; + view.setUint32(x, RpcReplyStat.MSG_ACCEPTED, false); + x += 4; + writer.x = x; + this.writeOpaqueAuth(verf); + writer.u32(acceptStat); + if (mismatchInfo) { + writer.u32(mismatchInfo.low); + writer.u32(mismatchInfo.high); + } + if (results) { + if (results instanceof Uint8Array) { + if (results.length > 0) writer.buf(results, results.length); + } else { + const size = results.size(); + if (size > 0) writer.buf(results.uint8, size); + } + } + } + + public writeRejectedReply( + xid: number, + rejectStat: number, + mismatchInfo?: {low: number; high: number}, + authStat?: number, + ): void { + const writer = this.writer; + writer.ensureCapacity(7 * 4); + const view = writer.view; + let x = writer.x; + view.setUint32(x, xid, false); + x += 4; + view.setUint32(x, RpcMsgType.REPLY, false); + x += 4; + view.setUint32(x, RpcReplyStat.MSG_DENIED, false); + x += 4; + view.setUint32(x, rejectStat, false); + x += 4; + if (mismatchInfo) { + view.setUint32(x, mismatchInfo.low, false); + x += 4; + view.setUint32(x, mismatchInfo.high, false); + x += 4; + } + if (authStat !== undefined) { + view.setUint32(x, authStat, false); + x += 4; + } + writer.x = x; + } + + private writeOpaqueAuth(auth: RpcOpaqueAuth): void { + const writer = this.writer; + const body = auth.body; + const length = body.size(); + if (length > 400) throw new RpcEncodingError('Auth body too large'); + writer.ensureCapacity(2 * 4 + length + 3); + const view = writer.view; + let x = writer.x; + view.setUint32(x, auth.flavor, false); + x += 4; + view.setUint32(x, length, false); + x += 4; + if (length > 0) { + writer.x = x; + writer.buf(body.subarray(0, length), length); + x = writer.x; + const padding = (4 - (length % 4)) % 4; + for (let i = 0; i < padding; i++) { + view.setUint8(x, 0); + x += 1; + } + } + writer.x = x; + } +} diff --git a/src/rpc/__tests__/RFC_SUMMARY.md b/src/rpc/__tests__/RFC_SUMMARY.md new file mode 100644 index 00000000..506ce896 --- /dev/null +++ b/src/rpc/__tests__/RFC_SUMMARY.md @@ -0,0 +1,37 @@ +### Overview + +The Remote Procedure Call (RPC) protocol specifications in RFC 1057, RFC 1831, and RFC 5531 all describe Version 2 of the ONC RPC protocol, originally developed by Sun Microsystems. RFC 1057 (published in 1988) introduced Version 2, obsoleting the earlier Version 1 (RFC 1050). RFC 1831 (1995) updated and obsoleted RFC 1057 with enhancements for better interoperability and scalability. RFC 5531 (2009) further obsoleted RFC 1831, advancing it to Internet Standard status with clarifications, security updates, and administrative changes, but without altering the underlying wire protocol. All versions maintain core elements like transport independence, XDR-based data representation, and support for programs, versions, and procedures. The differences primarily involve refinements in data handling, authentication, error management, and administration. + +### Key Differences Between RFC 1057 and RFC 1831 + +RFC 1831 built on RFC 1057 by addressing deployment experiences, improving efficiency, and standardizing elements for broader use. Notable changes include: + +- **Data Representation and Size Limits**: RFC 1831 references updated XDR (RFC 1832) to support larger opaque authentication bodies (up to 400 bytes) and fragment sizes in record marking (up to 2^31-1 bytes for stream transports like TCP), overcoming limitations in RFC 1057 for handling bigger messages. +- **Batching Support**: Explicitly defined in RFC 1831 as a feature for pipelining sequences of calls without immediate replies over reliable transports (terminated by a standard call), which was less detailed and formalized in RFC 1057. +- **Broadcast and Multicast RPC**: RFC 1831 added explicit support for multicast RPC over packet-based protocols like UDP, extending the broadcast capabilities mentioned in RFC 1057 (where servers respond only on success). +- **Authentication Mechanisms**: + - RFC 1831 introduced AUTH_SHORT (flavor 2) for shorthand credentials to reduce bandwidth via caching, which was present but less emphasized in RFC 1057. + - Standardized naming: AUTH_NULL became AUTH_NONE (0), AUTH_UNIX became AUTH_SYS (1), and AUTH_DES (3) was refined but moved to optional status. + - Clearer structures for opaque_auth and extensible flavors, with central assignment via rpc@sun.com. +- **Program Number Assignment**: Updated ranges in RFC 1831 (e.g., 0-1fffffff for defined, 20000000-3fffffff for user-defined, 40000000-5fffffff for transient), with more organized administration compared to RFC 1057's simpler scheme. +- **Error Handling and Message Structure**: More precise enums for accept_stat and auth_stat, expanded rejection reasons, and a formal record marking standard for TCP to improve error recovery—enhancements over RFC 1057's basic handling. +- **RPC Language Syntax**: RFC 1831 added notes on name spaces, constants, and syntax rules (e.g., unsigned constants only), formalizing what was less explicit in RFC 1057. +- **Other Enhancements**: References to updated standards (e.g., RFC 1700 for assigned numbers) and better interoperability for multiple program versions, while remaining backward-compatible. + +### Key Differences Between RFC 1831 and RFC 5531 + +RFC 5531 focused on clarifications, security improvements, and transitioning administration to IANA, without changing the protocol's on-the-wire behavior. It reflects over a decade of deployment experience and aligns with modern IETF practices. Key updates include: + +- **Administrative Changes**: + - Authority for assigning program numbers, authentication flavors, and status numbers shifted from Sun Microsystems to IANA, with new policies (e.g., First Come First Served for small blocks, Specification Required for larger ones). + - Added Appendix B for requesting assignments and Appendix C listing existing Sun-assigned numbers (e.g., portmapper=100000, NFS=100003), plus detailed ranges like 0x20000000-0x3fffffff for site-specific use. +- **Authentication Mechanisms**: + - Expanded flavors: Added AUTH_DH (3, marked obsolete and insecure per RFC 2695), AUTH_KERB (4), AUTH_RSA (5), RPCSEC_GSS (6 for GSS-based security with integrity/privacy per RFC 2203 and RFC 5403), and pseudo-flavors like AUTH_SPNEGO (390000 series for Kerberos V5 per RFC 2623)—beyond RFC 1831's AUTH_NONE, AUTH_SYS, and AUTH_SHORT. + - New authentication errors in auth_stat enum (e.g., RPCSEC_GSS_CREDPROBLEM=13, RPCSEC_GSS_CTXPROBLEM=14) for RPCSEC_GSS support. + - AUTH_SYS lacks a verifier and SHOULD NOT be used for modifiable data; future Standards Track RPC programs MUST support RPCSEC_GSS. +- **Security Considerations**: Enhanced section emphasizing risks of weak flavors (e.g., AUTH_NONE, AUTH_SYS) and mandating stronger security for new services. Recommends external measures like privileged ports and aligns with RFC 2623 for NFS security—more comprehensive than RFC 1831's basic notes. +- **RPC Language and Protocol Clarifications**: + - Aligned syntax with current usage (e.g., single type-specifier per argument, use structs for multiples; explicit identifier and constant rules). + - Refined error handling (e.g., added SYSTEM_ERR=5 to accept_stat for issues like memory allocation; clearer xid usage for deduplication only). + - Updated XDR reference to RFC 4506 (STD 67) and requirements language per RFC 2119 (MUST/SHOULD keywords). +- **Other Updates**: Incorporated IETF intellectual property statements, normative references (e.g., TCP per RFC 793, UDP per RFC 768), and formalizations for batching/broadcast without protocol changes. No new features, but improved precision for transports and semantics. diff --git a/src/rpc/__tests__/decoder.spec.ts b/src/rpc/__tests__/decoder.spec.ts new file mode 100644 index 00000000..fa709edd --- /dev/null +++ b/src/rpc/__tests__/decoder.spec.ts @@ -0,0 +1,849 @@ +import {RpcMessageDecoder} from '../RpcMessageDecoder'; +import {RpcAuthFlavor, RpcAcceptStat, RpcRejectStat, RpcAuthStat, RPC_VERSION} from '../constants'; +import {RpcCallMessage, RpcAcceptedReplyMessage, RpcRejectedReplyMessage} from '../messages'; +import {Reader} from '@jsonjoy.com/buffers/lib/Reader'; + +describe('RpcMessageDecoder', () => { + describe('CALL messages', () => { + test('can decode a simple CALL message with AUTH_NULL', () => { + const decoder = new RpcMessageDecoder(); + const payload = new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x01, // xid = 1 + 0x00, + 0x00, + 0x00, + 0x00, // msg_type = CALL + 0x00, + 0x00, + 0x00, + 0x02, // rpcvers = 2 + 0x00, + 0x00, + 0x01, + 0x86, // prog = 390 (NFS) + 0x00, + 0x00, + 0x00, + 0x02, // vers = 2 + 0x00, + 0x00, + 0x00, + 0x00, // proc = 0 (NULL) + 0x00, + 0x00, + 0x00, + 0x00, // cred.flavor = AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // cred.length = 0 + 0x00, + 0x00, + 0x00, + 0x00, // verf.flavor = AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // verf.length = 0 + ]); + const reader = new Reader(payload); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + expect(msg).toBeInstanceOf(RpcCallMessage); + expect(msg.xid).toBe(1); + const call = msg as RpcCallMessage; + expect(call.rpcvers).toBe(RPC_VERSION); + expect(call.prog).toBe(390); + expect(call.vers).toBe(2); + expect(call.proc).toBe(0); + expect(call.cred.flavor).toBe(RpcAuthFlavor.AUTH_NULL); + expect(call.cred.body.size()).toBe(0); + expect(call.verf.flavor).toBe(RpcAuthFlavor.AUTH_NULL); + expect(call.verf.body.size()).toBe(0); + }); + + test('can decode CALL message with opaque auth data', () => { + const decoder = new RpcMessageDecoder(); + const payload = new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x0a, // xid = 10 + 0x00, + 0x00, + 0x00, + 0x00, // msg_type = CALL + 0x00, + 0x00, + 0x00, + 0x02, // rpcvers = 2 + 0x00, + 0x00, + 0x00, + 0x64, // prog = 100 + 0x00, + 0x00, + 0x00, + 0x01, // vers = 1 + 0x00, + 0x00, + 0x00, + 0x01, // proc = 1 + 0x00, + 0x00, + 0x00, + 0x01, // cred.flavor = AUTH_UNIX + 0x00, + 0x00, + 0x00, + 0x05, // cred.length = 5 + 0x01, + 0x02, + 0x03, + 0x04, + 0x05, // cred.body + 0x00, + 0x00, + 0x00, // padding (3 bytes) + 0x00, + 0x00, + 0x00, + 0x00, // verf.flavor = AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // verf.length = 0 + ]); + const reader = new Reader(payload); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + expect(msg.xid).toBe(10); + const call = msg as RpcCallMessage; + expect(call.cred.flavor).toBe(RpcAuthFlavor.AUTH_UNIX); + expect(call.cred.body.buf()).toEqual(new Uint8Array([0x01, 0x02, 0x03, 0x04, 0x05])); + }); + + test('returns undefined when not enough data', () => { + const decoder = new RpcMessageDecoder(); + const payload = new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x01, // xid = 1 + 0x00, + 0x00, + 0x00, + 0x00, // msg_type = CALL + 0x00, + 0x00, + 0x00, + 0x02, // rpcvers = 2 + ]); + const reader = new Reader(payload.slice(0, 10)); + const msg = decoder.decodeMessage(reader); + expect(msg).toBeUndefined(); + }); + + test('returns undefined when message is incomplete', () => { + const decoder = new RpcMessageDecoder(); + const payload = new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x01, // xid = 1 + 0x00, + 0x00, + 0x00, + 0x00, // msg_type = CALL + 0x00, + 0x00, + 0x00, + 0x02, // rpcvers = 2 + 0x00, + 0x00, + 0x01, + 0x86, // prog = 390 + 0x00, + 0x00, + 0x00, + 0x02, // vers = 2 + 0x00, + 0x00, + 0x00, + 0x00, // proc = 0 + 0x00, + 0x00, + 0x00, + 0x00, // cred.flavor = AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // cred.length = 0 + 0x00, + 0x00, + 0x00, + 0x00, // verf.flavor = AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // verf.length = 0 + ]); + const chunk1 = payload.slice(0, 20); + let reader = new Reader(chunk1); + expect(decoder.decodeMessage(reader)).toBeUndefined(); + reader = new Reader(payload); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + expect(msg.xid).toBe(1); + }); + }); + + describe('REPLY messages - MSG_ACCEPTED', () => { + test('can decode SUCCESS reply', () => { + const decoder = new RpcMessageDecoder(); + const payload = new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x01, // xid = 1 + 0x00, + 0x00, + 0x00, + 0x01, // msg_type = REPLY + 0x00, + 0x00, + 0x00, + 0x00, // reply_stat = MSG_ACCEPTED + 0x00, + 0x00, + 0x00, + 0x00, // verf.flavor = AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // verf.length = 0 + 0x00, + 0x00, + 0x00, + 0x00, // accept_stat = SUCCESS + 0x00, + 0x00, + 0x00, + 0x2a, // results (example: 42) + ]); + + const reader = new Reader(payload); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + expect(msg.xid).toBe(1); + expect(msg).toBeInstanceOf(RpcAcceptedReplyMessage); + const reply = msg as RpcAcceptedReplyMessage; + expect(reply.stat).toBe(RpcAcceptStat.SUCCESS); + }); + + test('can decode PROG_UNAVAIL reply', () => { + const decoder = new RpcMessageDecoder(); + const payload = new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x02, // xid = 2 + 0x00, + 0x00, + 0x00, + 0x01, // msg_type = REPLY + 0x00, + 0x00, + 0x00, + 0x00, // reply_stat = MSG_ACCEPTED + 0x00, + 0x00, + 0x00, + 0x00, // verf.flavor = AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // verf.length = 0 + 0x00, + 0x00, + 0x00, + 0x01, // accept_stat = PROG_UNAVAIL + ]); + + const reader = new Reader(payload); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + expect(msg.xid).toBe(2); + const reply = msg as RpcAcceptedReplyMessage; + expect(reply.stat).toBe(RpcAcceptStat.PROG_UNAVAIL); + }); + + test('can decode PROG_MISMATCH reply', () => { + const decoder = new RpcMessageDecoder(); + const payload = new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x03, // xid = 3 + 0x00, + 0x00, + 0x00, + 0x01, // msg_type = REPLY + 0x00, + 0x00, + 0x00, + 0x00, // reply_stat = MSG_ACCEPTED + 0x00, + 0x00, + 0x00, + 0x00, // verf.flavor = AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // verf.length = 0 + 0x00, + 0x00, + 0x00, + 0x02, // accept_stat = PROG_MISMATCH + 0x00, + 0x00, + 0x00, + 0x01, // low = 1 + 0x00, + 0x00, + 0x00, + 0x03, // high = 3 + ]); + + const reader = new Reader(payload); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + expect(msg.xid).toBe(3); + const reply = msg as RpcAcceptedReplyMessage; + expect(reply.stat).toBe(RpcAcceptStat.PROG_MISMATCH); + expect(reply.mismatchInfo).toBeDefined(); + expect(reply.mismatchInfo!.low).toBe(1); + expect(reply.mismatchInfo!.high).toBe(3); + }); + + test('can decode PROC_UNAVAIL reply', () => { + const decoder = new RpcMessageDecoder(); + const payload = new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x04, // xid = 4 + 0x00, + 0x00, + 0x00, + 0x01, // msg_type = REPLY + 0x00, + 0x00, + 0x00, + 0x00, // reply_stat = MSG_ACCEPTED + 0x00, + 0x00, + 0x00, + 0x00, // verf.flavor = AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // verf.length = 0 + 0x00, + 0x00, + 0x00, + 0x03, // accept_stat = PROC_UNAVAIL + ]); + + const reader = new Reader(payload); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + expect(msg.xid).toBe(4); + const reply = msg as RpcAcceptedReplyMessage; + expect(reply.stat).toBe(RpcAcceptStat.PROC_UNAVAIL); + }); + + test('can decode GARBAGE_ARGS reply', () => { + const decoder = new RpcMessageDecoder(); + const payload = new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x05, // xid = 5 + 0x00, + 0x00, + 0x00, + 0x01, // msg_type = REPLY + 0x00, + 0x00, + 0x00, + 0x00, // reply_stat = MSG_ACCEPTED + 0x00, + 0x00, + 0x00, + 0x00, // verf.flavor = AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // verf.length = 0 + 0x00, + 0x00, + 0x00, + 0x04, // accept_stat = GARBAGE_ARGS + ]); + + const reader = new Reader(payload); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + expect(msg.xid).toBe(5); + const reply = msg as RpcAcceptedReplyMessage; + expect(reply.stat).toBe(RpcAcceptStat.GARBAGE_ARGS); + }); + }); + + describe('REPLY messages - MSG_DENIED', () => { + test('can decode RPC_MISMATCH reply', () => { + const decoder = new RpcMessageDecoder(); + const payload = new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x06, // xid = 6 + 0x00, + 0x00, + 0x00, + 0x01, // msg_type = REPLY + 0x00, + 0x00, + 0x00, + 0x01, // reply_stat = MSG_DENIED + 0x00, + 0x00, + 0x00, + 0x00, // reject_stat = RPC_MISMATCH + 0x00, + 0x00, + 0x00, + 0x02, // low = 2 + 0x00, + 0x00, + 0x00, + 0x02, // high = 2 + ]); + + const reader = new Reader(payload); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + expect(msg.xid).toBe(6); + expect(msg).toBeInstanceOf(RpcRejectedReplyMessage); + const reply = msg as RpcRejectedReplyMessage; + expect(reply.stat).toBe(RpcRejectStat.RPC_MISMATCH); + expect(reply.mismatchInfo).toBeDefined(); + expect(reply.mismatchInfo!.low).toBe(2); + expect(reply.mismatchInfo!.high).toBe(2); + }); + + test('can decode AUTH_ERROR reply', () => { + const decoder = new RpcMessageDecoder(); + const payload = new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x07, // xid = 7 + 0x00, + 0x00, + 0x00, + 0x01, // msg_type = REPLY + 0x00, + 0x00, + 0x00, + 0x01, // reply_stat = MSG_DENIED + 0x00, + 0x00, + 0x00, + 0x01, // reject_stat = AUTH_ERROR + 0x00, + 0x00, + 0x00, + 0x01, // auth_stat = AUTH_BADCRED + ]); + + const reader = new Reader(payload); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + expect(msg.xid).toBe(7); + const reply = msg as RpcRejectedReplyMessage; + expect(reply.stat).toBe(RpcRejectStat.AUTH_ERROR); + expect(reply.authStat).toBe(RpcAuthStat.AUTH_BADCRED); + }); + }); + + describe('multiple messages', () => { + test('can decode multiple messages from stream', () => { + const decoder = new RpcMessageDecoder(); + const payload1 = new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x01, // xid = 1 + 0x00, + 0x00, + 0x00, + 0x00, // msg_type = CALL + 0x00, + 0x00, + 0x00, + 0x02, // rpcvers = 2 + 0x00, + 0x00, + 0x00, + 0x64, // prog = 100 + 0x00, + 0x00, + 0x00, + 0x01, // vers = 1 + 0x00, + 0x00, + 0x00, + 0x00, // proc = 0 + 0x00, + 0x00, + 0x00, + 0x00, // cred.flavor = AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // cred.length = 0 + 0x00, + 0x00, + 0x00, + 0x00, // verf.flavor = AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // verf.length = 0 + ]); + const payload2 = new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x02, // xid = 2 + 0x00, + 0x00, + 0x00, + 0x00, // msg_type = CALL + 0x00, + 0x00, + 0x00, + 0x02, // rpcvers = 2 + 0x00, + 0x00, + 0x00, + 0xc8, // prog = 200 + 0x00, + 0x00, + 0x00, + 0x01, // vers = 1 + 0x00, + 0x00, + 0x00, + 0x01, // proc = 1 + 0x00, + 0x00, + 0x00, + 0x00, // cred.flavor = AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // cred.length = 0 + 0x00, + 0x00, + 0x00, + 0x00, // verf.flavor = AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // verf.length = 0 + ]); + + const reader1 = new Reader(payload1); + const message1 = decoder.decodeMessage(reader1)!; + expect(message1).toBeDefined(); + expect(message1.xid).toBe(1); + expect((message1 as RpcCallMessage).prog).toBe(100); + + const reader2 = new Reader(payload2); + const message2 = decoder.decodeMessage(reader2)!; + expect(message2).toBeDefined(); + expect(message2.xid).toBe(2); + expect((message2 as RpcCallMessage).prog).toBe(200); + }); + }); + + describe('Payload Handling', () => { + test('can decode CALL with procedure parameters', () => { + const decoder = new RpcMessageDecoder(); + const params = new Uint8Array([0x00, 0x00, 0x00, 0x2a, 0x00, 0x00, 0x00, 0x45]); + const payload = new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x01, // xid = 1 + 0x00, + 0x00, + 0x00, + 0x00, // msg_type = CALL + 0x00, + 0x00, + 0x00, + 0x02, // rpcvers = 2 + 0x00, + 0x00, + 0x00, + 0x64, // prog = 100 + 0x00, + 0x00, + 0x00, + 0x01, // vers = 1 + 0x00, + 0x00, + 0x00, + 0x01, // proc = 1 + 0x00, + 0x00, + 0x00, + 0x00, // cred.flavor = AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // cred.length = 0 + 0x00, + 0x00, + 0x00, + 0x00, // verf.flavor = AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // verf.length = 0 + ...params, + ]); + + const reader = new Reader(payload); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + expect(msg.xid).toBe(1); + const call = msg as RpcCallMessage; + expect(call.proc).toBe(1); + expect(call.params).toBeDefined(); + expect(call.params!.buf(call.params!.size())).toEqual(params); + }); + + test('can decode SUCCESS reply with result data', () => { + const decoder = new RpcMessageDecoder(); + const results = new Uint8Array([0x00, 0x00, 0x00, 0x7b]); + const payload = new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x01, // xid = 1 + 0x00, + 0x00, + 0x00, + 0x01, // msg_type = REPLY + 0x00, + 0x00, + 0x00, + 0x00, // reply_stat = MSG_ACCEPTED + 0x00, + 0x00, + 0x00, + 0x00, // verf.flavor = AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // verf.length = 0 + 0x00, + 0x00, + 0x00, + 0x00, // accept_stat = SUCCESS + ...results, + ]); + + const reader = new Reader(payload); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + expect(msg.xid).toBe(1); + const reply = msg as RpcAcceptedReplyMessage; + expect(reply.stat).toBe(RpcAcceptStat.SUCCESS); + expect(reply.results).toBeDefined(); + expect(reply.results!.buf(reply.results!.size())).toEqual(results); + }); + + test('handles CALL with no parameters', () => { + const decoder = new RpcMessageDecoder(); + const payload = new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x01, // xid = 1 + 0x00, + 0x00, + 0x00, + 0x00, // msg_type = CALL + 0x00, + 0x00, + 0x00, + 0x02, // rpcvers = 2 + 0x00, + 0x00, + 0x00, + 0x64, // prog = 100 + 0x00, + 0x00, + 0x00, + 0x01, // vers = 1 + 0x00, + 0x00, + 0x00, + 0x00, // proc = 0 (NULL) + 0x00, + 0x00, + 0x00, + 0x00, // cred.flavor = AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // cred.length = 0 + 0x00, + 0x00, + 0x00, + 0x00, // verf.flavor = AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // verf.length = 0 + ]); + + const reader = new Reader(payload); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + const call = msg as RpcCallMessage; + expect(call.params).toBeUndefined(); + }); + + test('handles REPLY with no result data', () => { + const decoder = new RpcMessageDecoder(); + const payload = new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x01, // xid = 1 + 0x00, + 0x00, + 0x00, + 0x01, // msg_type = REPLY + 0x00, + 0x00, + 0x00, + 0x00, // reply_stat = MSG_ACCEPTED + 0x00, + 0x00, + 0x00, + 0x00, // verf.flavor = AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // verf.length = 0 + 0x00, + 0x00, + 0x00, + 0x01, // accept_stat = PROG_UNAVAIL + ]); + + const reader = new Reader(payload); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + const reply = msg as RpcAcceptedReplyMessage; + expect(reply.results).toBeUndefined(); + }); + + test('decodes PORTMAP_GETPORT with parameters correctly', () => { + const decoder = new RpcMessageDecoder(); + const params = new Uint8Array([ + 0x00, + 0x01, + 0x86, + 0xa3, // prog: 100003 + 0x00, + 0x00, + 0x00, + 0x03, // vers: 3 + 0x00, + 0x00, + 0x00, + 0x11, // protocol: 17 (UDP) + 0x00, + 0x00, + 0x00, + 0x00, // port: 0 + ]); + const payload = new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x9c, // XID: 156 + 0x00, + 0x00, + 0x00, + 0x00, // msg_type: CALL (0) + 0x00, + 0x00, + 0x00, + 0x02, // rpcvers: 2 + 0x00, + 0x01, + 0x86, + 0xa0, // prog: 100000 (PORTMAP) + 0x00, + 0x00, + 0x00, + 0x02, // vers: 2 + 0x00, + 0x00, + 0x00, + 0x03, // proc: 3 (GETPORT) + 0x00, + 0x00, + 0x00, + 0x00, // cred: AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // cred length: 0 + 0x00, + 0x00, + 0x00, + 0x00, // verf: AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // verf length: 0 + ...params, + ]); + + const reader = new Reader(payload); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + expect(msg.xid).toBe(156); + const call = msg as RpcCallMessage; + expect(call.prog).toBe(100000); + expect(call.vers).toBe(2); + expect(call.proc).toBe(3); + expect(call.params).toBeDefined(); + expect(call.params!.buf(call.params!.size())).toEqual(params); + }); + }); +}); diff --git a/src/rpc/__tests__/encoder.spec.ts b/src/rpc/__tests__/encoder.spec.ts new file mode 100644 index 00000000..c0cbe2bd --- /dev/null +++ b/src/rpc/__tests__/encoder.spec.ts @@ -0,0 +1,314 @@ +import {RpcMessageEncoder} from '../RpcMessageEncoder'; +import {RpcMessageDecoder} from '../RpcMessageDecoder'; +import {RpcAuthFlavor, RpcAcceptStat, RpcRejectStat, RpcAuthStat, RPC_VERSION} from '../constants'; +import {RpcOpaqueAuth, RpcCallMessage, RpcAcceptedReplyMessage, RpcRejectedReplyMessage, RpcMessage} from '../messages'; +import {Reader} from '@jsonjoy.com/buffers/lib/Reader'; + +describe('RpcMessageEncoder', () => { + describe('CALL messages', () => { + test('can encode a simple CALL message with AUTH_NULL', () => { + const encoder = new RpcMessageEncoder(); + const cred = new RpcOpaqueAuth(RpcAuthFlavor.AUTH_NULL, new Reader(new Uint8Array(0))); + const verf = new RpcOpaqueAuth(RpcAuthFlavor.AUTH_NULL, new Reader(new Uint8Array(0))); + const encoded = encoder.encodeCall(1, 100, 1, 0, cred, verf); + const decoder = new RpcMessageDecoder(); + const reader = new Reader(encoded); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + expect(msg.xid).toBe(1); + expect(msg).toBeInstanceOf(RpcCallMessage); + const call = msg as RpcCallMessage; + expect(call.rpcvers).toBe(RPC_VERSION); + expect(call.prog).toBe(100); + expect(call.vers).toBe(1); + expect(call.proc).toBe(0); + expect(call.cred.flavor).toBe(RpcAuthFlavor.AUTH_NULL); + expect(call.verf.flavor).toBe(RpcAuthFlavor.AUTH_NULL); + }); + + test('can encode CALL message with opaque auth data', () => { + const encoder = new RpcMessageEncoder(); + const credBody = new Reader(new Uint8Array([1, 2, 3, 4, 5])); + const cred = new RpcOpaqueAuth(RpcAuthFlavor.AUTH_UNIX, credBody); + const verf = new RpcOpaqueAuth(RpcAuthFlavor.AUTH_NULL, new Reader(new Uint8Array(0))); + const encoded = encoder.encodeCall(10, 200, 2, 5, cred, verf); + const decoder = new RpcMessageDecoder(); + const reader = new Reader(encoded); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + expect(msg.xid).toBe(10); + const call = msg as RpcCallMessage; + expect(call.prog).toBe(200); + expect(call.vers).toBe(2); + expect(call.proc).toBe(5); + expect(call.cred.flavor).toBe(RpcAuthFlavor.AUTH_UNIX); + expect(call.cred.body.buf()).toEqual(new Uint8Array([1, 2, 3, 4, 5])); + }); + + test('can encode CALL message with parameters', () => { + const encoder = new RpcMessageEncoder(); + const cred = new RpcOpaqueAuth(RpcAuthFlavor.AUTH_NULL, new Reader(new Uint8Array(0))); + const verf = new RpcOpaqueAuth(RpcAuthFlavor.AUTH_NULL, new Reader(new Uint8Array(0))); + const params = new Uint8Array([0, 0, 0, 42]); + const encoded = encoder.encodeCall(15, 300, 1, 3, cred, verf, params); + expect(encoded.length).toBeGreaterThan(40); + const decoder = new RpcMessageDecoder(); + const reader = new Reader(encoded); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + expect(msg.xid).toBe(15); + }); + + test('can encode CALL with RpcMessage object', () => { + const encoder = new RpcMessageEncoder(); + const cred = new RpcOpaqueAuth(RpcAuthFlavor.AUTH_NULL, new Reader(new Uint8Array(0))); + const verf = new RpcOpaqueAuth(RpcAuthFlavor.AUTH_NULL, new Reader(new Uint8Array(0))); + const msg = new RpcCallMessage(20, RPC_VERSION, 100, 1, 0, cred, verf); + const encoded = encoder.encodeMessage(msg); + const decoder = new RpcMessageDecoder(); + const reader = new Reader(encoded); + const decoded = decoder.decodeMessage(reader)!; + expect(decoded).toBeDefined(); + expect(decoded.xid).toBe(20); + expect((decoded as RpcCallMessage).prog).toBe(100); + }); + }); + + describe('REPLY messages - MSG_ACCEPTED', () => { + test('can encode SUCCESS reply', () => { + const encoder = new RpcMessageEncoder(); + const verf = new RpcOpaqueAuth(RpcAuthFlavor.AUTH_NULL, new Reader(new Uint8Array(0))); + const results = new Uint8Array([0, 0, 0, 42]); + const encoded = encoder.encodeAcceptedReply(1, verf, RpcAcceptStat.SUCCESS, undefined, results); + const decoder = new RpcMessageDecoder(); + const reader = new Reader(encoded); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + expect(msg.xid).toBe(1); + expect(msg).toBeInstanceOf(RpcAcceptedReplyMessage); + const reply = msg as RpcAcceptedReplyMessage; + expect(reply.stat).toBe(RpcAcceptStat.SUCCESS); + }); + + test('can encode PROG_UNAVAIL reply', () => { + const encoder = new RpcMessageEncoder(); + const verf = new RpcOpaqueAuth(RpcAuthFlavor.AUTH_NULL, new Reader(new Uint8Array(0))); + const encoded = encoder.encodeAcceptedReply(2, verf, RpcAcceptStat.PROG_UNAVAIL); + const decoder = new RpcMessageDecoder(); + const reader = new Reader(encoded); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + expect(msg.xid).toBe(2); + const reply = msg as RpcAcceptedReplyMessage; + expect(reply.stat).toBe(RpcAcceptStat.PROG_UNAVAIL); + }); + + test('can encode PROG_MISMATCH reply', () => { + const encoder = new RpcMessageEncoder(); + const verf = new RpcOpaqueAuth(RpcAuthFlavor.AUTH_NULL, new Reader(new Uint8Array(0))); + const mismatchInfo = {low: 1, high: 3}; + const encoded = encoder.encodeAcceptedReply(3, verf, RpcAcceptStat.PROG_MISMATCH, mismatchInfo); + const decoder = new RpcMessageDecoder(); + const reader = new Reader(encoded); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + expect(msg.xid).toBe(3); + const reply = msg as RpcAcceptedReplyMessage; + expect(reply.stat).toBe(RpcAcceptStat.PROG_MISMATCH); + expect(reply.mismatchInfo).toBeDefined(); + expect(reply.mismatchInfo!.low).toBe(1); + expect(reply.mismatchInfo!.high).toBe(3); + }); + + test('can encode PROC_UNAVAIL reply', () => { + const encoder = new RpcMessageEncoder(); + const verf = new RpcOpaqueAuth(RpcAuthFlavor.AUTH_NULL, new Reader(new Uint8Array(0))); + const encoded = encoder.encodeAcceptedReply(4, verf, RpcAcceptStat.PROC_UNAVAIL); + const decoder = new RpcMessageDecoder(); + const reader = new Reader(encoded); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + expect(msg.xid).toBe(4); + const reply = msg as RpcAcceptedReplyMessage; + expect(reply.stat).toBe(RpcAcceptStat.PROC_UNAVAIL); + }); + + test('can encode GARBAGE_ARGS reply', () => { + const encoder = new RpcMessageEncoder(); + const verf = new RpcOpaqueAuth(RpcAuthFlavor.AUTH_NULL, new Reader(new Uint8Array(0))); + const encoded = encoder.encodeAcceptedReply(5, verf, RpcAcceptStat.GARBAGE_ARGS); + const decoder = new RpcMessageDecoder(); + const reader = new Reader(encoded); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + expect(msg.xid).toBe(5); + const reply = msg as RpcAcceptedReplyMessage; + expect(reply.stat).toBe(RpcAcceptStat.GARBAGE_ARGS); + }); + + test('can encode AcceptedReply with RpcMessage object', () => { + const encoder = new RpcMessageEncoder(); + const verf = new RpcOpaqueAuth(RpcAuthFlavor.AUTH_NULL, new Reader(new Uint8Array(0))); + const msg = new RpcAcceptedReplyMessage(25, verf, RpcAcceptStat.SUCCESS); + const encoded = encoder.encodeMessage(msg); + const decoder = new RpcMessageDecoder(); + const reader = new Reader(encoded); + const decoded = decoder.decodeMessage(reader)!; + expect(decoded).toBeDefined(); + expect(decoded.xid).toBe(25); + expect((decoded as RpcAcceptedReplyMessage).stat).toBe(RpcAcceptStat.SUCCESS); + }); + }); + + describe('REPLY messages - MSG_DENIED', () => { + test('can encode RPC_MISMATCH reply', () => { + const encoder = new RpcMessageEncoder(); + const mismatchInfo = {low: 2, high: 2}; + const encoded = encoder.encodeRejectedReply(6, RpcRejectStat.RPC_MISMATCH, mismatchInfo); + const decoder = new RpcMessageDecoder(); + const reader = new Reader(encoded); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + expect(msg.xid).toBe(6); + expect(msg).toBeInstanceOf(RpcRejectedReplyMessage); + const reply = msg as RpcRejectedReplyMessage; + expect(reply.stat).toBe(RpcRejectStat.RPC_MISMATCH); + expect(reply.mismatchInfo).toBeDefined(); + expect(reply.mismatchInfo!.low).toBe(2); + expect(reply.mismatchInfo!.high).toBe(2); + }); + + test('can encode AUTH_ERROR reply', () => { + const encoder = new RpcMessageEncoder(); + const encoded = encoder.encodeRejectedReply(7, RpcRejectStat.AUTH_ERROR, undefined, RpcAuthStat.AUTH_BADCRED); + const decoder = new RpcMessageDecoder(); + const reader = new Reader(encoded); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + expect(msg.xid).toBe(7); + const reply = msg as RpcRejectedReplyMessage; + expect(reply.stat).toBe(RpcRejectStat.AUTH_ERROR); + expect(reply.authStat).toBe(RpcAuthStat.AUTH_BADCRED); + }); + + test('can encode RejectedReply with RpcMessage object', () => { + const encoder = new RpcMessageEncoder(); + const msg = new RpcRejectedReplyMessage(30, RpcRejectStat.AUTH_ERROR, undefined, RpcAuthStat.AUTH_TOOWEAK); + const encoded = encoder.encodeMessage(msg); + const decoder = new RpcMessageDecoder(); + const reader = new Reader(encoded); + const decoded = decoder.decodeMessage(reader)!; + expect(decoded).toBeDefined(); + expect(decoded.xid).toBe(30); + const reply = decoded as RpcRejectedReplyMessage; + expect(reply.stat).toBe(RpcRejectStat.AUTH_ERROR); + expect(reply.authStat).toBe(RpcAuthStat.AUTH_TOOWEAK); + }); + }); + + describe('round-trip encoding/decoding', () => { + test('multiple messages can be encoded and decoded', () => { + const encoder = new RpcMessageEncoder(); + const decoder = new RpcMessageDecoder(); + const cred = new RpcOpaqueAuth(RpcAuthFlavor.AUTH_NULL, new Reader(new Uint8Array(0))); + const verf = new RpcOpaqueAuth(RpcAuthFlavor.AUTH_NULL, new Reader(new Uint8Array(0))); + const encoded1 = encoder.encodeCall(100, 1000, 1, 0, cred, verf); + const encoded2 = encoder.encodeCall(101, 1001, 1, 1, cred, verf); + const encoded3 = encoder.encodeAcceptedReply(100, verf, RpcAcceptStat.SUCCESS); + const reader1 = new Reader(encoded1); + const msg1 = decoder.decodeMessage(reader1)!; + expect(msg1.xid).toBe(100); + expect((msg1 as RpcCallMessage).prog).toBe(1000); + const reader2 = new Reader(encoded2); + const msg2 = decoder.decodeMessage(reader2)!; + expect(msg2.xid).toBe(101); + expect((msg2 as RpcCallMessage).prog).toBe(1001); + const reader3 = new Reader(encoded3); + const msg3 = decoder.decodeMessage(reader3)!; + expect(msg3.xid).toBe(100); + expect((msg3 as RpcAcceptedReplyMessage).stat).toBe(RpcAcceptStat.SUCCESS); + }); + + test('handles auth body padding correctly', () => { + const encoder = new RpcMessageEncoder(); + const decoder = new RpcMessageDecoder(); + const credBody1 = new Uint8Array([1]); + const credBody2 = new Uint8Array([1, 2]); + const credBody3 = new Uint8Array([1, 2, 3]); + const credBody4 = new Uint8Array([1, 2, 3, 4]); + const verf = new RpcOpaqueAuth(RpcAuthFlavor.AUTH_NULL, new Reader(new Uint8Array(0))); + const testCred = (body: Uint8Array, xid: number) => { + const cred = new RpcOpaqueAuth(RpcAuthFlavor.AUTH_UNIX, new Reader(body)); + const encoded = encoder.encodeCall(xid, 100, 1, 0, cred, verf); + const reader = new Reader(encoded); + const msg = decoder.decodeMessage(reader)!; + expect(msg.xid).toBe(xid); + expect((msg as RpcCallMessage).cred.body.buf()).toEqual(body); + }; + testCred(credBody1, 1); + testCred(credBody2, 2); + testCred(credBody3, 3); + testCred(credBody4, 4); + }); + }); + + describe('Payload Encoding', () => { + test('encodes CALL with procedure parameters', () => { + const encoder = new RpcMessageEncoder(); + const decoder = new RpcMessageDecoder(); + const cred = new RpcOpaqueAuth(RpcAuthFlavor.AUTH_NULL, new Reader(new Uint8Array(0))); + const verf = new RpcOpaqueAuth(RpcAuthFlavor.AUTH_NULL, new Reader(new Uint8Array(0))); + const params = new Uint8Array([0x00, 0x00, 0x00, 0x2a, 0x00, 0x00, 0x00, 0x45]); + const encoded = encoder.encodeCall(1, 100, 1, 1, cred, verf, params); + const reader = new Reader(encoded); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + const call = msg as RpcCallMessage; + expect(call.params).toBeDefined(); + expect(call.params!.buf(call.params!.size())).toEqual(params); + }); + + test('encodes REPLY with result data', () => { + const encoder = new RpcMessageEncoder(); + const decoder = new RpcMessageDecoder(); + const verf = new RpcOpaqueAuth(RpcAuthFlavor.AUTH_NULL, new Reader(new Uint8Array(0))); + const results = new Uint8Array([0x00, 0x00, 0x00, 0x7b]); + const encoded = encoder.encodeAcceptedReply(1, verf, RpcAcceptStat.SUCCESS, undefined, results); + const reader = new Reader(encoded); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + const reply = msg as RpcAcceptedReplyMessage; + expect(reply.results).toBeDefined(); + expect(reply.results!.buf(reply.results!.size())).toEqual(results); + }); + + test('encodes RpcCallMessage with params field via encodeMessage', () => { + const encoder = new RpcMessageEncoder(); + const decoder = new RpcMessageDecoder(); + const cred = new RpcOpaqueAuth(RpcAuthFlavor.AUTH_NULL, new Reader(new Uint8Array(0))); + const verf = new RpcOpaqueAuth(RpcAuthFlavor.AUTH_NULL, new Reader(new Uint8Array(0))); + const params = new Uint8Array([0x12, 0x34, 0x56, 0x78]); + const msg = new RpcCallMessage(1, RPC_VERSION, 100, 1, 1, cred, verf, new Reader(params)); + const encoded = encoder.encodeMessage(msg); + const reader = new Reader(encoded); + const decoded = decoder.decodeMessage(reader)!; + expect(decoded).toBeDefined(); + const decodedCall = decoded as RpcCallMessage; + expect(decodedCall.params?.buf(decodedCall.params.size())).toEqual(params); + }); + + test('encodes RpcAcceptedReplyMessage with results field via encodeMessage', () => { + const encoder = new RpcMessageEncoder(); + const decoder = new RpcMessageDecoder(); + const verf = new RpcOpaqueAuth(RpcAuthFlavor.AUTH_NULL, new Reader(new Uint8Array(0))); + const results = new Uint8Array([0x00, 0x00, 0x01, 0x00]); + const msg = new RpcAcceptedReplyMessage(1, verf, RpcAcceptStat.SUCCESS, undefined, new Reader(results)); + const encoded = encoder.encodeMessage(msg); + const reader = new Reader(encoded); + const decoded = decoder.decodeMessage(reader)!; + expect(decoded).toBeDefined(); + const decodedReply = decoded as RpcAcceptedReplyMessage; + expect(decodedReply.results?.buf(decodedReply.results.size())).toEqual(results); + }); + }); +}); diff --git a/src/rpc/__tests__/fixtures.spec.ts b/src/rpc/__tests__/fixtures.spec.ts new file mode 100644 index 00000000..ad81d7d2 --- /dev/null +++ b/src/rpc/__tests__/fixtures.spec.ts @@ -0,0 +1,382 @@ +import {RpcMessageDecoder} from '../RpcMessageDecoder'; +import {RpcMessageEncoder} from '../RpcMessageEncoder'; +import {RpcCallMessage, RpcAcceptedReplyMessage, RpcRejectedReplyMessage} from '../messages'; +import {Reader} from '@jsonjoy.com/buffers/lib/Reader'; +import {RpcAcceptStat, RpcRejectStat} from '../constants'; +import * as fixtures from './fixtures'; + +describe('RPC Real-world Fixtures', () => { + describe('Decoding fixtures', () => { + test.each(fixtures.ALL_FIXTURES)('$name - can decode byte-for-byte', (fixture) => { + const decoder = new RpcMessageDecoder(); + const reader = new Reader(fixture.bytes); + const msg = decoder.decodeMessage(reader); + expect(msg).toBeDefined(); + expect(msg!.xid).toBe(fixture.expected.xid); + if (fixture.expected.type === 'CALL') { + expect(msg!).toBeInstanceOf(RpcCallMessage); + const call = msg! as RpcCallMessage; + if (fixture.expected.rpcvers !== undefined) { + expect(call.rpcvers).toBe(fixture.expected.rpcvers); + } + if (fixture.expected.prog !== undefined) { + expect(call.prog).toBe(fixture.expected.prog); + } + if (fixture.expected.vers !== undefined) { + expect(call.vers).toBe(fixture.expected.vers); + } + if (fixture.expected.proc !== undefined) { + expect(call.proc).toBe(fixture.expected.proc); + } + if (fixture.expected.credFlavor !== undefined) { + expect(call.cred.flavor).toBe(fixture.expected.credFlavor); + } + if (fixture.expected.verfFlavor !== undefined) { + expect(call.verf.flavor).toBe(fixture.expected.verfFlavor); + } + if (fixture.expected.credBodyLength !== undefined) { + expect(call.cred.body.buf().length).toBe(fixture.expected.credBodyLength); + } + } else if (fixture.expected.type === 'REPLY') { + if (fixture.expected.replyStat === 'MSG_ACCEPTED') { + expect(msg!).toBeInstanceOf(RpcAcceptedReplyMessage); + const reply = msg! as RpcAcceptedReplyMessage; + if (fixture.expected.acceptStat !== undefined) { + expect(reply.stat).toBe(fixture.expected.acceptStat); + } + if (fixture.expected.verfFlavor !== undefined) { + expect(reply.verf.flavor).toBe(fixture.expected.verfFlavor); + } + if (fixture.expected.mismatchLow !== undefined) { + expect(reply.mismatchInfo).toBeDefined(); + expect(reply.mismatchInfo!.low).toBe(fixture.expected.mismatchLow); + expect(reply.mismatchInfo!.high).toBe(fixture.expected.mismatchHigh); + } + } else if (fixture.expected.replyStat === 'MSG_DENIED') { + expect(msg!).toBeInstanceOf(RpcRejectedReplyMessage); + const reply = msg! as RpcRejectedReplyMessage; + if (fixture.expected.rejectStat !== undefined) { + expect(reply.stat).toBe(fixture.expected.rejectStat); + } + if (fixture.expected.mismatchLow !== undefined) { + expect(reply.mismatchInfo).toBeDefined(); + expect(reply.mismatchInfo!.low).toBe(fixture.expected.mismatchLow); + expect(reply.mismatchInfo!.high).toBe(fixture.expected.mismatchHigh); + } + if (fixture.expected.authStat !== undefined) { + expect(reply.authStat).toBe(fixture.expected.authStat); + } + } + } + }); + }); + + describe('Round-trip encoding/decoding', () => { + test.each(fixtures.ALL_FIXTURES)('$name - round-trip preserves structure', (fixture) => { + const decoder1 = new RpcMessageDecoder(); + const withRecordMarking = fixture.bytes; + const reader1 = new Reader(withRecordMarking); + const msg1 = decoder1.decodeMessage(reader1)!; + expect(msg1).toBeDefined(); + const encoder = new RpcMessageEncoder(); + const encoded = encoder.encodeMessage(msg1); + const decoder2 = new RpcMessageDecoder(); + const reader2 = new Reader(encoded); + const msg2 = decoder2.decodeMessage(reader2)!; + expect(msg2).toBeDefined(); + expect(msg2.xid).toBe(msg1.xid); + if (msg1 instanceof RpcCallMessage) { + expect(msg2).toBeInstanceOf(RpcCallMessage); + const call1 = msg1 as RpcCallMessage; + const call2 = msg2 as RpcCallMessage; + expect(call2.rpcvers).toBe(call1.rpcvers); + expect(call2.prog).toBe(call1.prog); + expect(call2.vers).toBe(call1.vers); + expect(call2.proc).toBe(call1.proc); + expect(call2.cred.flavor).toBe(call1.cred.flavor); + expect(call2.cred.body.subarray()).toEqual(call1.cred.body.subarray()); + expect(call2.verf.flavor).toBe(call1.verf.flavor); + expect(call2.verf.body.subarray()).toEqual(call1.verf.body.subarray()); + } else if (msg1 instanceof RpcAcceptedReplyMessage) { + expect(msg2).toBeInstanceOf(RpcAcceptedReplyMessage); + const reply1 = msg1 as RpcAcceptedReplyMessage; + const reply2 = msg2 as RpcAcceptedReplyMessage; + expect(reply2.stat).toBe(reply1.stat); + expect(reply2.verf.flavor).toBe(reply1.verf.flavor); + if (reply1.mismatchInfo) { + expect(reply2.mismatchInfo).toBeDefined(); + expect(reply2.mismatchInfo!.low).toBe(reply1.mismatchInfo.low); + expect(reply2.mismatchInfo!.high).toBe(reply1.mismatchInfo.high); + } + } else if (msg1 instanceof RpcRejectedReplyMessage) { + expect(msg2).toBeInstanceOf(RpcRejectedReplyMessage); + const reply1 = msg1 as RpcRejectedReplyMessage; + const reply2 = msg2 as RpcRejectedReplyMessage; + expect(reply2.stat).toBe(reply1.stat); + if (reply1.mismatchInfo) { + expect(reply2.mismatchInfo).toBeDefined(); + expect(reply2.mismatchInfo!.low).toBe(reply1.mismatchInfo.low); + expect(reply2.mismatchInfo!.high).toBe(reply1.mismatchInfo.high); + } + if (reply1.authStat !== undefined) { + expect(reply2.authStat).toBe(reply1.authStat); + } + } + }); + }); + + describe('Streaming decode', () => { + test('can decode message in small chunks', () => { + const decoder = new RpcMessageDecoder(); + const bytes = fixtures.NFS_NULL_CALL.bytes; + const reader = new Reader(bytes); + const msg = decoder.decodeMessage(reader); + expect(msg).toBeDefined(); + expect(msg!.xid).toBe(1); + }); + + test('can decode multiple messages from stream', () => { + const decoder = new RpcMessageDecoder(); + const reader1 = new Reader(fixtures.NFS_NULL_CALL.bytes); + const msg1 = decoder.decodeMessage(reader1); + expect(msg1).toBeDefined(); + expect(msg1!.xid).toBe(1); + const reader2 = new Reader(fixtures.SUCCESS_REPLY.bytes); + const msg2 = decoder.decodeMessage(reader2); + expect(msg2).toBeDefined(); + expect(msg2!.xid).toBe(156); + const reader3 = new Reader(fixtures.PROG_UNAVAIL_REPLY.bytes); + const msg3 = decoder.decodeMessage(reader3); + expect(msg3).toBeDefined(); + expect(msg3!.xid).toBe(66); + }); + + test('handles partial messages correctly', () => { + const decoder = new RpcMessageDecoder(); + const bytes = fixtures.CALL_WITH_AUTH_UNIX.bytes; + let reader = new Reader(bytes.slice(0, 20)); + expect(decoder.decodeMessage(reader)).toBeUndefined(); + reader = new Reader(bytes); + const msg = decoder.decodeMessage(reader); + expect(msg).toBeDefined(); + expect(msg!.xid).toBe(1234); + }); + + test('can decode multiple messages from stream', () => { + const decoder = new RpcMessageDecoder(); + const reader1 = new Reader(fixtures.NFS_NULL_CALL.bytes); + const msg1 = decoder.decodeMessage(reader1); + expect(msg1).toBeDefined(); + expect(msg1!.xid).toBe(1); + const reader2 = new Reader(fixtures.SUCCESS_REPLY.bytes); + const msg2 = decoder.decodeMessage(reader2); + expect(msg2).toBeDefined(); + expect(msg2!.xid).toBe(156); + const reader3 = new Reader(fixtures.PROG_UNAVAIL_REPLY.bytes); + const msg3 = decoder.decodeMessage(reader3); + expect(msg3).toBeDefined(); + expect(msg3!.xid).toBe(66); + }); + }); + + describe('XDR padding validation', () => { + test.each([fixtures.CALL_WITH_PADDING_1BYTE, fixtures.CALL_WITH_PADDING_2BYTE, fixtures.CALL_WITH_PADDING_3BYTE])( + '$name - correctly handles padding', + (fixture) => { + const decoder = new RpcMessageDecoder(); + const withRecordMarking = fixture.bytes; + const reader = new Reader(withRecordMarking); + const msg = decoder.decodeMessage(reader)!; + expect(msg).toBeDefined(); + const call = msg as RpcCallMessage; + expect(call.cred.body.buf().length).toBe(fixture.expected.credBodyLength); + const encoder = new RpcMessageEncoder(); + const encoded = encoder.encodeMessage(msg); + expect(encoded.length % 4).toBe(0); + }, + ); + }); + + describe('Error handling', () => { + test('handles invalid message type', () => { + const decoder = new RpcMessageDecoder(); + const invalidBytes = new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x01, // XID + 0x00, + 0x00, + 0x00, + 0x99, // Invalid msg_type + ]); + const withRecordMarking = invalidBytes; + const reader = new Reader(withRecordMarking); + expect(() => decoder.decodeMessage(reader)).toThrow(); + }); + + test.skip('handles invalid RPC version', () => { + const decoder = new RpcMessageDecoder(); + const invalidBytes = new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x01, // XID + 0x00, + 0x00, + 0x00, + 0x00, // CALL + 0x00, + 0x00, + 0x00, + 0x99, // Invalid RPC version + 0x00, + 0x00, + 0x00, + 0x01, // prog + 0x00, + 0x00, + 0x00, + 0x01, // vers + 0x00, + 0x00, + 0x00, + 0x00, // proc + 0x00, + 0x00, + 0x00, + 0x00, // cred flavor + 0x00, + 0x00, + 0x00, + 0x00, // cred length + 0x00, + 0x00, + 0x00, + 0x00, // verf flavor + 0x00, + 0x00, + 0x00, + 0x00, // verf length + ]); + const withRecordMarking = invalidBytes; + const reader = new Reader(withRecordMarking); + expect(() => decoder.decodeMessage(reader)).toThrow(); + }); + + test('handles oversized auth body', () => { + const decoder = new RpcMessageDecoder(); + const invalidBytes = new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x01, // XID + 0x00, + 0x00, + 0x00, + 0x00, // CALL + 0x00, + 0x00, + 0x00, + 0x02, // RPC version + 0x00, + 0x00, + 0x00, + 0x01, // prog + 0x00, + 0x00, + 0x00, + 0x01, // vers + 0x00, + 0x00, + 0x00, + 0x00, // proc + 0x00, + 0x00, + 0x00, + 0x01, // cred flavor + 0xff, + 0xff, + 0xff, + 0xff, // oversized length + ]); + const withRecordMarking = invalidBytes; + const reader = new Reader(withRecordMarking); + expect(() => decoder.decodeMessage(reader)).toThrow(); + }); + + test('handles invalid reply_stat', () => { + const decoder = new RpcMessageDecoder(); + const invalidBytes = new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x01, // XID + 0x00, + 0x00, + 0x00, + 0x01, // REPLY + 0x00, + 0x00, + 0x00, + 0x99, // Invalid reply_stat + ]); + const withRecordMarking = invalidBytes; + const reader = new Reader(withRecordMarking); + expect(() => decoder.decodeMessage(reader)).toThrow(); + }); + }); + + describe('NFS-specific scenarios', () => { + test('NFS NULL call should have no parameters', () => { + const decoder = new RpcMessageDecoder(); + const withRecordMarking = fixtures.NFS_NULL_CALL.bytes; + const reader = new Reader(withRecordMarking); + const msg = decoder.decodeMessage(reader)!; + const call = msg as RpcCallMessage; + expect(call.prog).toBe(100003); + expect(call.proc).toBe(0); + expect(call.cred.body.size()).toBe(0); + expect(call.verf.body.size()).toBe(0); + }); + + test('GETPORT response format is valid', () => { + const decoder = new RpcMessageDecoder(); + const withRecordMarking = fixtures.SUCCESS_REPLY.bytes; + const reader = new Reader(withRecordMarking); + const msg = decoder.decodeMessage(reader)!; + const reply = msg as RpcAcceptedReplyMessage; + expect(reply.stat).toBe(RpcAcceptStat.SUCCESS); + }); + }); + + describe('Performance tests', () => { + test('can decode 1000 messages quickly', () => { + const decoder = new RpcMessageDecoder(); + const withRecordMarking = fixtures.NFS_NULL_CALL.bytes; + const start = Date.now(); + for (let i = 0; i < 1000; i++) { + const reader = new Reader(withRecordMarking); + const msg = decoder.decodeMessage(reader); + expect(msg).toBeDefined(); + } + const elapsed = Date.now() - start; + expect(elapsed).toBeLessThan(1000); + }); + + test('can encode 1000 messages quickly', () => { + const encoder = new RpcMessageEncoder(); + const decoder = new RpcMessageDecoder(); + const withRecordMarking = fixtures.NFS_NULL_CALL.bytes; + const reader = new Reader(withRecordMarking); + const template = decoder.decodeMessage(reader)!; + const start = Date.now(); + for (let i = 0; i < 1000; i++) { + const encoded = encoder.encodeMessage(template); + expect(encoded).toBeDefined(); + } + const elapsed = Date.now() - start; + expect(elapsed).toBeLessThan(1000); + }); + }); +}); diff --git a/src/rpc/__tests__/fixtures.ts b/src/rpc/__tests__/fixtures.ts new file mode 100644 index 00000000..13593ea3 --- /dev/null +++ b/src/rpc/__tests__/fixtures.ts @@ -0,0 +1,815 @@ +import {RpcAuthFlavor, RpcAcceptStat, RpcRejectStat, RpcAuthStat, RPC_VERSION} from '../constants'; + +/** + * Real-world RPC message fixtures based on RFC 1057 and NFS implementations. + * All fixtures are byte-for-byte representations of actual RPC messages. + */ + +export interface RpcFixture { + name: string; + description: string; + bytes: Uint8Array; + expected: { + xid: number; + type: 'CALL' | 'REPLY'; + [key: string]: any; + }; +} + +/** + * Adds RFC 1057 record marking to a raw RPC message payload. + * The record mark is a 4-byte header with the high bit set (last fragment) + * and the lower 31 bits containing the fragment length. + */ +export function addRecordMarking(payload: Uint8Array): Uint8Array { + const length = payload.length; + const header = 0x80000000 | length; + const result = new Uint8Array(4 + length); + const view = new DataView(result.buffer); + view.setUint32(0, header, false); + result.set(payload, 4); + return result; +} + +/** + * NFS NULL procedure call - simplest RPC call + * Source: Common NFS implementations + */ +export const NFS_NULL_CALL: RpcFixture = { + name: 'NFS NULL CALL', + description: 'NFS NULL procedure call with AUTH_NULL credentials', + bytes: new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x01, // XID: 1 + 0x00, + 0x00, + 0x00, + 0x00, // msg_type: CALL (0) + 0x00, + 0x00, + 0x00, + 0x02, // rpcvers: 2 + 0x00, + 0x01, + 0x86, + 0xa3, // prog: 100003 (NFS) + 0x00, + 0x00, + 0x00, + 0x03, // vers: 3 + 0x00, + 0x00, + 0x00, + 0x00, // proc: 0 (NULL) + 0x00, + 0x00, + 0x00, + 0x00, // cred: AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // cred length: 0 + 0x00, + 0x00, + 0x00, + 0x00, // verf: AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // verf length: 0 + ]), + expected: { + xid: 1, + type: 'CALL', + rpcvers: RPC_VERSION, + prog: 100003, + vers: 3, + proc: 0, + credFlavor: RpcAuthFlavor.AUTH_NULL, + verfFlavor: RpcAuthFlavor.AUTH_NULL, + }, +}; + +/** + * Portmapper GETPORT call + * Source: RFC 1057, Section A.2 + */ +export const PORTMAP_GETPORT: RpcFixture = { + name: 'PORTMAP GETPORT', + description: 'Portmapper GETPORT procedure call', + bytes: new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x9c, // XID: 156 + 0x00, + 0x00, + 0x00, + 0x00, // msg_type: CALL (0) + 0x00, + 0x00, + 0x00, + 0x02, // rpcvers: 2 + 0x00, + 0x01, + 0x86, + 0xa0, // prog: 100000 (PORTMAP) + 0x00, + 0x00, + 0x00, + 0x02, // vers: 2 + 0x00, + 0x00, + 0x00, + 0x03, // proc: 3 (GETPORT) + 0x00, + 0x00, + 0x00, + 0x00, // cred: AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // cred length: 0 + 0x00, + 0x00, + 0x00, + 0x00, // verf: AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // verf length: 0 + // Parameters: prog=100003, vers=3, prot=17, port=0 + 0x00, + 0x01, + 0x86, + 0xa3, // prog: 100003 + 0x00, + 0x00, + 0x00, + 0x03, // vers: 3 + 0x00, + 0x00, + 0x00, + 0x11, // protocol: 17 (UDP) + 0x00, + 0x00, + 0x00, + 0x00, // port: 0 + ]), + expected: { + xid: 156, + type: 'CALL', + rpcvers: RPC_VERSION, + prog: 100000, + vers: 2, + proc: 3, + credFlavor: RpcAuthFlavor.AUTH_NULL, + verfFlavor: RpcAuthFlavor.AUTH_NULL, + }, +}; + +/** + * RPC call with AUTH_UNIX credentials + * Source: RFC 1057, Section 9.2 + */ +export const CALL_WITH_AUTH_UNIX: RpcFixture = { + name: 'CALL with AUTH_UNIX', + description: 'RPC call with AUTH_UNIX credentials (uid=1000, gid=1000)', + bytes: new Uint8Array([ + 0x00, + 0x00, + 0x04, + 0xd2, // XID: 1234 + 0x00, + 0x00, + 0x00, + 0x00, // msg_type: CALL (0) + 0x00, + 0x00, + 0x00, + 0x02, // rpcvers: 2 + 0x00, + 0x01, + 0x86, + 0xa3, // prog: 100003 (NFS) + 0x00, + 0x00, + 0x00, + 0x03, // vers: 3 + 0x00, + 0x00, + 0x00, + 0x01, // proc: 1 + 0x00, + 0x00, + 0x00, + 0x01, // cred: AUTH_UNIX + 0x00, + 0x00, + 0x00, + 0x18, // cred length: 24 + // AUTH_UNIX data (24 bytes) + 0x00, + 0x00, + 0x00, + 0x00, // stamp: 0 + 0x00, + 0x00, + 0x00, + 0x04, // machine name length: 4 + 0x74, + 0x65, + 0x73, + 0x74, // machine name: "test" + 0x00, + 0x00, + 0x03, + 0xe8, // uid: 1000 + 0x00, + 0x00, + 0x03, + 0xe8, // gid: 1000 + 0x00, + 0x00, + 0x00, + 0x00, // gids length: 0 + 0x00, + 0x00, + 0x00, + 0x00, // verf: AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // verf length: 0 + ]), + expected: { + xid: 1234, + type: 'CALL', + rpcvers: RPC_VERSION, + prog: 100003, + vers: 3, + proc: 1, + credFlavor: RpcAuthFlavor.AUTH_UNIX, + verfFlavor: RpcAuthFlavor.AUTH_NULL, + }, +}; + +/** + * Successful RPC reply (no result data) + * Source: RFC 1057, Section A.3 + * Note: Result data is not included as it should be handled separately by the application + */ +export const SUCCESS_REPLY: RpcFixture = { + name: 'SUCCESS REPLY', + description: 'Successful RPC reply without result data', + bytes: new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x9c, // XID: 156 + 0x00, + 0x00, + 0x00, + 0x01, // msg_type: REPLY (1) + 0x00, + 0x00, + 0x00, + 0x00, // reply_stat: MSG_ACCEPTED (0) + 0x00, + 0x00, + 0x00, + 0x00, // verf: AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // verf length: 0 + 0x00, + 0x00, + 0x00, + 0x00, // accept_stat: SUCCESS (0) + ]), + expected: { + xid: 156, + type: 'REPLY', + replyStat: 'MSG_ACCEPTED', + acceptStat: RpcAcceptStat.SUCCESS, + verfFlavor: RpcAuthFlavor.AUTH_NULL, + }, +}; + +/** + * PROG_UNAVAIL reply + */ +export const PROG_UNAVAIL_REPLY: RpcFixture = { + name: 'PROG_UNAVAIL REPLY', + description: 'Reply indicating program unavailable', + bytes: new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x42, // XID: 66 + 0x00, + 0x00, + 0x00, + 0x01, // msg_type: REPLY (1) + 0x00, + 0x00, + 0x00, + 0x00, // reply_stat: MSG_ACCEPTED (0) + 0x00, + 0x00, + 0x00, + 0x00, // verf: AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // verf length: 0 + 0x00, + 0x00, + 0x00, + 0x01, // accept_stat: PROG_UNAVAIL (1) + ]), + expected: { + xid: 66, + type: 'REPLY', + replyStat: 'MSG_ACCEPTED', + acceptStat: RpcAcceptStat.PROG_UNAVAIL, + verfFlavor: RpcAuthFlavor.AUTH_NULL, + }, +}; + +/** + * PROG_MISMATCH reply + */ +export const PROG_MISMATCH_REPLY: RpcFixture = { + name: 'PROG_MISMATCH REPLY', + description: 'Reply indicating program version mismatch', + bytes: new Uint8Array([ + 0x00, + 0x00, + 0x01, + 0x00, // XID: 256 + 0x00, + 0x00, + 0x00, + 0x01, // msg_type: REPLY (1) + 0x00, + 0x00, + 0x00, + 0x00, // reply_stat: MSG_ACCEPTED (0) + 0x00, + 0x00, + 0x00, + 0x00, // verf: AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // verf length: 0 + 0x00, + 0x00, + 0x00, + 0x02, // accept_stat: PROG_MISMATCH (2) + 0x00, + 0x00, + 0x00, + 0x02, // low version: 2 + 0x00, + 0x00, + 0x00, + 0x03, // high version: 3 + ]), + expected: { + xid: 256, + type: 'REPLY', + replyStat: 'MSG_ACCEPTED', + acceptStat: RpcAcceptStat.PROG_MISMATCH, + verfFlavor: RpcAuthFlavor.AUTH_NULL, + mismatchLow: 2, + mismatchHigh: 3, + }, +}; + +/** + * PROC_UNAVAIL reply + */ +export const PROC_UNAVAIL_REPLY: RpcFixture = { + name: 'PROC_UNAVAIL REPLY', + description: 'Reply indicating procedure unavailable', + bytes: new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x55, // XID: 85 + 0x00, + 0x00, + 0x00, + 0x01, // msg_type: REPLY (1) + 0x00, + 0x00, + 0x00, + 0x00, // reply_stat: MSG_ACCEPTED (0) + 0x00, + 0x00, + 0x00, + 0x00, // verf: AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // verf length: 0 + 0x00, + 0x00, + 0x00, + 0x03, // accept_stat: PROC_UNAVAIL (3) + ]), + expected: { + xid: 85, + type: 'REPLY', + replyStat: 'MSG_ACCEPTED', + acceptStat: RpcAcceptStat.PROC_UNAVAIL, + verfFlavor: RpcAuthFlavor.AUTH_NULL, + }, +}; + +/** + * GARBAGE_ARGS reply + */ +export const GARBAGE_ARGS_REPLY: RpcFixture = { + name: 'GARBAGE_ARGS REPLY', + description: 'Reply indicating garbage arguments', + bytes: new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x99, // XID: 153 + 0x00, + 0x00, + 0x00, + 0x01, // msg_type: REPLY (1) + 0x00, + 0x00, + 0x00, + 0x00, // reply_stat: MSG_ACCEPTED (0) + 0x00, + 0x00, + 0x00, + 0x00, // verf: AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // verf length: 0 + 0x00, + 0x00, + 0x00, + 0x04, // accept_stat: GARBAGE_ARGS (4) + ]), + expected: { + xid: 153, + type: 'REPLY', + replyStat: 'MSG_ACCEPTED', + acceptStat: RpcAcceptStat.GARBAGE_ARGS, + verfFlavor: RpcAuthFlavor.AUTH_NULL, + }, +}; + +/** + * RPC_MISMATCH rejected reply + */ +export const RPC_MISMATCH_REPLY: RpcFixture = { + name: 'RPC_MISMATCH REPLY', + description: 'Rejected reply due to RPC version mismatch', + bytes: new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0x77, // XID: 119 + 0x00, + 0x00, + 0x00, + 0x01, // msg_type: REPLY (1) + 0x00, + 0x00, + 0x00, + 0x01, // reply_stat: MSG_DENIED (1) + 0x00, + 0x00, + 0x00, + 0x00, // reject_stat: RPC_MISMATCH (0) + 0x00, + 0x00, + 0x00, + 0x02, // low version: 2 + 0x00, + 0x00, + 0x00, + 0x02, // high version: 2 + ]), + expected: { + xid: 119, + type: 'REPLY', + replyStat: 'MSG_DENIED', + rejectStat: RpcRejectStat.RPC_MISMATCH, + mismatchLow: 2, + mismatchHigh: 2, + }, +}; + +/** + * AUTH_ERROR rejected reply with AUTH_BADCRED + */ +export const AUTH_BADCRED_REPLY: RpcFixture = { + name: 'AUTH_BADCRED REPLY', + description: 'Rejected reply due to bad credentials', + bytes: new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0xaa, // XID: 170 + 0x00, + 0x00, + 0x00, + 0x01, // msg_type: REPLY (1) + 0x00, + 0x00, + 0x00, + 0x01, // reply_stat: MSG_DENIED (1) + 0x00, + 0x00, + 0x00, + 0x01, // reject_stat: AUTH_ERROR (1) + 0x00, + 0x00, + 0x00, + 0x01, // auth_stat: AUTH_BADCRED (1) + ]), + expected: { + xid: 170, + type: 'REPLY', + replyStat: 'MSG_DENIED', + rejectStat: RpcRejectStat.AUTH_ERROR, + authStat: RpcAuthStat.AUTH_BADCRED, + }, +}; + +/** + * AUTH_ERROR rejected reply with AUTH_TOOWEAK + */ +export const AUTH_TOOWEAK_REPLY: RpcFixture = { + name: 'AUTH_TOOWEAK REPLY', + description: 'Rejected reply due to weak authentication', + bytes: new Uint8Array([ + 0x00, + 0x00, + 0x00, + 0xbb, // XID: 187 + 0x00, + 0x00, + 0x00, + 0x01, // msg_type: REPLY (1) + 0x00, + 0x00, + 0x00, + 0x01, // reply_stat: MSG_DENIED (1) + 0x00, + 0x00, + 0x00, + 0x01, // reject_stat: AUTH_ERROR (1) + 0x00, + 0x00, + 0x00, + 0x05, // auth_stat: AUTH_TOOWEAK (5) + ]), + expected: { + xid: 187, + type: 'REPLY', + replyStat: 'MSG_DENIED', + rejectStat: RpcRejectStat.AUTH_ERROR, + authStat: RpcAuthStat.AUTH_TOOWEAK, + }, +}; + +/** + * Call with non-aligned auth body (tests XDR padding) + */ +export const CALL_WITH_PADDING_1BYTE: RpcFixture = { + name: 'CALL with 1-byte auth (3-byte padding)', + description: 'RPC call with 1-byte auth body requiring 3 bytes padding', + bytes: new Uint8Array([ + 0x00, + 0x00, + 0x11, + 0x11, // XID: 4369 + 0x00, + 0x00, + 0x00, + 0x00, // msg_type: CALL (0) + 0x00, + 0x00, + 0x00, + 0x02, // rpcvers: 2 + 0x00, + 0x00, + 0x00, + 0x64, // prog: 100 + 0x00, + 0x00, + 0x00, + 0x01, // vers: 1 + 0x00, + 0x00, + 0x00, + 0x00, // proc: 0 + 0x00, + 0x00, + 0x00, + 0x01, // cred: AUTH_UNIX + 0x00, + 0x00, + 0x00, + 0x01, // cred length: 1 + 0x42, + 0x00, + 0x00, + 0x00, // cred body: [0x42] + 3 padding bytes + 0x00, + 0x00, + 0x00, + 0x00, // verf: AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // verf length: 0 + ]), + expected: { + xid: 4369, + type: 'CALL', + rpcvers: RPC_VERSION, + prog: 100, + vers: 1, + proc: 0, + credFlavor: RpcAuthFlavor.AUTH_UNIX, + credBodyLength: 1, + verfFlavor: RpcAuthFlavor.AUTH_NULL, + }, +}; + +/** + * Call with 2-byte auth body (tests XDR padding) + */ +export const CALL_WITH_PADDING_2BYTE: RpcFixture = { + name: 'CALL with 2-byte auth (2-byte padding)', + description: 'RPC call with 2-byte auth body requiring 2 bytes padding', + bytes: new Uint8Array([ + 0x00, + 0x00, + 0x22, + 0x22, // XID: 8738 + 0x00, + 0x00, + 0x00, + 0x00, // msg_type: CALL (0) + 0x00, + 0x00, + 0x00, + 0x02, // rpcvers: 2 + 0x00, + 0x00, + 0x00, + 0x64, // prog: 100 + 0x00, + 0x00, + 0x00, + 0x01, // vers: 1 + 0x00, + 0x00, + 0x00, + 0x00, // proc: 0 + 0x00, + 0x00, + 0x00, + 0x01, // cred: AUTH_UNIX + 0x00, + 0x00, + 0x00, + 0x02, // cred length: 2 + 0x12, + 0x34, + 0x00, + 0x00, // cred body: [0x12, 0x34] + 2 padding bytes + 0x00, + 0x00, + 0x00, + 0x00, // verf: AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // verf length: 0 + ]), + expected: { + xid: 8738, + type: 'CALL', + rpcvers: RPC_VERSION, + prog: 100, + vers: 1, + proc: 0, + credFlavor: RpcAuthFlavor.AUTH_UNIX, + credBodyLength: 2, + verfFlavor: RpcAuthFlavor.AUTH_NULL, + }, +}; + +/** + * Call with 3-byte auth body (tests XDR padding) + */ +export const CALL_WITH_PADDING_3BYTE: RpcFixture = { + name: 'CALL with 3-byte auth (1-byte padding)', + description: 'RPC call with 3-byte auth body requiring 1 byte padding', + bytes: new Uint8Array([ + 0x00, + 0x00, + 0x33, + 0x33, // XID: 13107 + 0x00, + 0x00, + 0x00, + 0x00, // msg_type: CALL (0) + 0x00, + 0x00, + 0x00, + 0x02, // rpcvers: 2 + 0x00, + 0x00, + 0x00, + 0x64, // prog: 100 + 0x00, + 0x00, + 0x00, + 0x01, // vers: 1 + 0x00, + 0x00, + 0x00, + 0x00, // proc: 0 + 0x00, + 0x00, + 0x00, + 0x01, // cred: AUTH_UNIX + 0x00, + 0x00, + 0x00, + 0x03, // cred length: 3 + 0x12, + 0x34, + 0x56, + 0x00, // cred body: [0x12, 0x34, 0x56] + 1 padding byte + 0x00, + 0x00, + 0x00, + 0x00, // verf: AUTH_NULL + 0x00, + 0x00, + 0x00, + 0x00, // verf length: 0 + ]), + expected: { + xid: 13107, + type: 'CALL', + rpcvers: RPC_VERSION, + prog: 100, + vers: 1, + proc: 0, + credFlavor: RpcAuthFlavor.AUTH_UNIX, + credBodyLength: 3, + verfFlavor: RpcAuthFlavor.AUTH_NULL, + }, +}; + +/** + * All fixtures for easy iteration in tests + */ +export const ALL_FIXTURES: RpcFixture[] = [ + NFS_NULL_CALL, + PORTMAP_GETPORT, + CALL_WITH_AUTH_UNIX, + SUCCESS_REPLY, + PROG_UNAVAIL_REPLY, + PROG_MISMATCH_REPLY, + PROC_UNAVAIL_REPLY, + GARBAGE_ARGS_REPLY, + RPC_MISMATCH_REPLY, + AUTH_BADCRED_REPLY, + AUTH_TOOWEAK_REPLY, + CALL_WITH_PADDING_1BYTE, + CALL_WITH_PADDING_2BYTE, + CALL_WITH_PADDING_3BYTE, +]; + +/** + * CALL fixtures only + */ +export const CALL_FIXTURES = ALL_FIXTURES.filter((f) => f.expected.type === 'CALL'); + +/** + * REPLY fixtures only + */ +export const REPLY_FIXTURES = ALL_FIXTURES.filter((f) => f.expected.type === 'REPLY'); diff --git a/src/rpc/__tests__/real-traces.spec.ts b/src/rpc/__tests__/real-traces.spec.ts new file mode 100644 index 00000000..ef585e00 --- /dev/null +++ b/src/rpc/__tests__/real-traces.spec.ts @@ -0,0 +1,48 @@ +import {RmRecordDecoder} from '../../rm'; +import {RpcAcceptedReplyMessage, RpcAcceptStat, RpcCallMessage, RpcMessage} from '../messages'; +import {RpcMessageDecoder} from '../RpcMessageDecoder'; + +const rmDecoder = new RmRecordDecoder(); +const rpcDecoder = new RpcMessageDecoder(); + +const decode = (hex: string): RpcMessage | undefined => { + const msg = Buffer.from(hex, 'hex'); + const u8 = new Uint8Array(msg); + rmDecoder.push(u8); + const record = rmDecoder.readRecord(); + if (record) { + return rpcDecoder.decodeMessage(record); + } + return undefined; +}; + +const nfs3LookupCallHex = + '80000090eb8a42cb0000000000000002000186a30000000300000003000000010000003c00490e680000001d455042594d494e573039333554312e6d696e736b2e6570616d2e636f6d000000000001f40000000a000000020000000a000001f400000000000000000000001c9725bb51046621880c000000a68c020078286c3e00000000000000000000000568656c6c6f000000'; +const nfs3AccessCallHex = + '80000088ea8a42cb0000000000000002000186a30000000300000004000000010000003c00490e680000001d455042594d494e573039333554312e6d696e736b2e6570616d2e636f6d000000000001f40000000a000000020000000a000001f400000000000000000000001c9725bb51046621880c000000a68c020078286c3e00000000000000000000001f'; +const nfs3RaddirplusReplyHex = + '800001b4ed8a42cb0000000100000000000000000000000000000000000000000000000100000002000001ed00000002000001f400000000000000000000020000000000000008000000003c000a009700000000000000410000000000028ca651ed1cc20000000051ed1cb00000000051ed1cb0000000000000000000000f59000000010000000000028ca6000000012e000000000000000000000c0000000100000002000001ed00000002000001f400000000000000000000020000000000000008000000003c000a009700000000000000410000000000028ca651ed1cc20000000051ed1cb00000000051ed1cb000000000000000010000001c9725bb51046621880c000000a68c020078286c3e0000000000000000000000010000000000012665000000022e2e000000000000000002000000000100000002000001ff00000005000003ea000000000000000000000200000000000000080000000096000400df0000000000000041000000000001266551ec763d0000000051e69ed20000000051e69ed200000000000000010000001c9725bb51046621880c000000652601008072c43300000000000000000000000000000001'; + +test('RPC Call LOOKUP', () => { + const msg = decode(nfs3LookupCallHex) as RpcCallMessage; + expect(msg.xid).toBe(0xeb8a42cb); + expect(msg.rpcvers).toBe(2); + expect(msg.prog).toBe(100003); + expect(msg.vers).toBe(3); + expect(msg.proc).toBe(3); +}); + +test('RPC Call ACCESS', () => { + const msg = decode(nfs3AccessCallHex) as RpcCallMessage; + expect(msg.xid).toBe(0xea8a42cb); + expect(msg.rpcvers).toBe(2); + expect(msg.prog).toBe(100003); + expect(msg.vers).toBe(3); + expect(msg.proc).toBe(4); +}); + +test('RPC Reply READDIRPLUS', () => { + const msg = decode(nfs3RaddirplusReplyHex) as RpcAcceptedReplyMessage; + expect(msg.xid).toBe(3985261259); + expect(msg.stat).toBe(RpcAcceptStat.SUCCESS); +}); diff --git a/src/rpc/__tests__/rfc1057.txt b/src/rpc/__tests__/rfc1057.txt new file mode 100644 index 00000000..1237f257 --- /dev/null +++ b/src/rpc/__tests__/rfc1057.txt @@ -0,0 +1,1396 @@ +Network Working Group Sun Microsystems, Inc. +Request For Comments: 1057 June 1988 +Obsoletes: RFC 1050 + + + RPC: Remote Procedure Call + Protocol Specification + Version 2 + +STATUS OF THIS MEMO + + This RFC describes a standard that Sun Microsystems and others are + using, and is one we wish to propose for the Internet's + consideration. This memo is not an Internet standard at this time. + Distribution of this memo is unlimited. + +1. INTRODUCTION + + This document specifies version two of the message protocol used in + Sun's Remote Procedure Call (RPC) package. The message protocol is + specified with the eXternal Data Representation (XDR) language [9]. + This document assumes that the reader is familiar with XDR. It does + not attempt to justify remote procedure calls systems or describe + their use. The paper by Birrell and Nelson [1] is recommended as an + excellent background for the remote procedure call concept. + +2. TERMINOLOGY + + This document discusses clients, calls, servers, replies, services, + programs, procedures, and versions. Each remote procedure call has + two sides: an active client side that sends the call to a server, + which sends back a reply. A network service is a collection of one + or more remote programs. A remote program implements one or more + remote procedures; the procedures, their parameters, and results are + documented in the specific program's protocol specification (see + Appendix A for an example). A server may support more than one + version of a remote program in order to be compatible with changing + protocols. + + For example, a network file service may be composed of two programs. + One program may deal with high-level applications such as file system + access control and locking. The other may deal with low-level file + input and output and have procedures like "read" and "write". A + client of the network file service would call the procedures + associated with the two programs of the service on behalf of the + client. + + The terms client and server only apply to a particular transaction; a + + + +Sun Microsystems [Page 1] + +RFC 1057 Remote Procedure Call, Version 2 June 1988 + + + particular hardware entity (host) or software entity (process or + program) could operate in both roles at different times. For + example, a program that supplies remote execution service could also + be a client of a network file service. On the other hand, it may + simplify software to separate client and server functionality into + separate libraries or programs. + +3. THE RPC MODEL + + The Sun RPC protocol is based on the remote procedure call model, + which is similar to the local procedure call model. In the local + case, the caller places arguments to a procedure in some well- + specified location (such as a register window). It then transfers + control to the procedure, and eventually regains control. At that + point, the results of the procedure are extracted from the well- + specified location, and the caller continues execution. + + The remote procedure call model is similar. One thread of control + logically winds through two processes: the caller's process, and a + server's process. The caller process first sends a call message to + the server process and waits (blocks) for a reply message. The call + message includes the procedure's parameters, and the reply message + includes the procedure's results. Once the reply message is + received, the results of the procedure are extracted, and caller's + execution is resumed. + + On the server side, a process is dormant awaiting the arrival of a + call message. When one arrives, the server process extracts the + procedure's parameters, computes the results, sends a reply message, + and then awaits the next call message. + + In this model, only one of the two processes is active at any given + time. However, this model is only given as an example. The Sun RPC + protocol makes no restrictions on the concurrency model implemented, + and others are possible. For example, an implementation may choose + to have RPC calls be asynchronous, so that the client may do useful + work while waiting for the reply from the server. Another + possibility is to have the server create a separate task to process + an incoming call, so that the original server can be free to receive + other requests. + + There are a few important ways in which remote procedure calls differ + from local procedure calls: + + 1. Error handling: failures of the remote server or network must be + handled when using remote procedure calls. + + 2. Global variables and side-effects: since the server does not have + + + +Sun Microsystems [Page 2] + +RFC 1057 Remote Procedure Call, Version 2 June 1988 + + + access to the client's address space, hidden arguments cannot be + passed as global variables or returned as side effects. + + 3. Performance: remote procedures usually operate one or more orders + of magnitude slower than local procedure calls. + + 4. Authentication: since remote procedure calls can be transported + over insecure networks, authentication may be necessary. + + The conclusion is that even though there are tools to automatically + generate client and server libraries for a given service, protocols + must still be designed carefully. + +4. TRANSPORTS AND SEMANTICS + + The RPC protocol can be implemented on several different transport + protocols. The RPC protocol does not care how a message is passed + from one process to another, but only with specification and + interpretation of messages. On the other hand, the application may + wish to obtain information about (and perhaps control over) the + transport layer through an interface not specified in this document. + For example, the transport protocol may impose a restriction on the + maximum size of RPC messages, or it may be stream-oriented like TCP + with no size limit. The client and server must agree on their + transport protocol choices, through a mechanism such as the one + described in Appendix A. + + It is important to point out that RPC does not try to implement any + kind of reliability and that the application may need to be aware of + the type of transport protocol underneath RPC. If it knows it is + running on top of a reliable transport such as TCP [6], then most of + the work is already done for it. On the other hand, if it is running + on top of an unreliable transport such as UDP [7], it must implement + its own time-out, retransmission, and duplicate detection policies as + the RPC layer does not provide these services. + + Because of transport independence, the RPC protocol does not attach + specific semantics to the remote procedures or their execution + requirements. Semantics can be inferred from (but should be + explicitly specified by) the underlying transport protocol. For + example, consider RPC running on top of an unreliable transport such + as UDP. If an application retransmits RPC call messages after time- + outs, and does not receive a reply, it cannot infer anything about + the number of times the procedure was executed. If it does receive a + reply, then it can infer that the procedure was executed at least + once. + + A server may wish to remember previously granted requests from a + + + +Sun Microsystems [Page 3] + +RFC 1057 Remote Procedure Call, Version 2 June 1988 + + + client and not regrant them in order to insure some degree of + execute-at-most-once semantics. A server can do this by taking + advantage of the transaction ID that is packaged with every RPC + message. The main use of this transaction is by the client RPC layer + in matching replies to calls. However, a client application may + choose to reuse its previous transaction ID when retransmitting a + call. The server may choose to remember this ID after executing a + call and not execute calls with the same ID in order to achieve some + degree of execute-at-most-once semantics. The server is not allowed + to examine this ID in any other way except as a test for equality. + + On the other hand, if using a "reliable" transport such as TCP, the + application can infer from a reply message that the procedure was + executed exactly once, but if it receives no reply message, it cannot + assume the remote procedure was not executed. Note that even if a + connection-oriented protocol like TCP is used, an application still + needs time-outs and reconnection to handle server crashes. + + There are other possibilities for transports besides datagram- or + connection-oriented protocols. For example, a request-reply protocol + such as VMTP [2] is perhaps a natural transport for RPC. The Sun RPC + package currently uses both TCP and UDP transport protocols, with + experimentation underway on others such as ISO TP4 and TP0. + +5. BINDING AND RENDEZVOUS INDEPENDENCE + + The act of binding a particular client to a particular service and + transport parameters is NOT part of this RPC protocol specification. + This important and necessary function is left up to some higher-level + software. (The software may use RPC itself; see Appendix A.) + + Implementors could think of the RPC protocol as the jump-subroutine + instruction ("JSR") of a network; the loader (binder) makes JSR + useful, and the loader itself uses JSR to accomplish its task. + Likewise, the binding software makes RPC useful, possibly using RPC + to accomplish this task. + +6. AUTHENTICATION + + The RPC protocol provides the fields necessary for a client to + identify itself to a service, and vice-versa, in each call and reply + message. Security and access control mechanisms can be built on top + of this message authentication. Several different authentication + protocols can be supported. A field in the RPC header indicates + which protocol is being used. More information on specific + authentication protocols is in section 9: "Authentication Protocols". + + + + + +Sun Microsystems [Page 4] + +RFC 1057 Remote Procedure Call, Version 2 June 1988 + + +7. RPC PROTOCOL REQUIREMENTS + + The RPC protocol must provide for the following: + + (1) Unique specification of a procedure to be called. + (2) Provisions for matching response messages to request messages. + (3) Provisions for authenticating the caller to service and vice- + versa. + + Besides these requirements, features that detect the following are + worth supporting because of protocol roll-over errors, implementation + bugs, user error, and network administration: + + (1) RPC protocol mismatches. + (2) Remote program protocol version mismatches. + (3) Protocol errors (such as misspecification of a procedure's + parameters). + (4) Reasons why remote authentication failed. + (5) Any other reasons why the desired procedure was not called. + +7.1 RPC Programs and Procedures + + The RPC call message has three unsigned integer fields -- remote + program number, remote program version number, and remote procedure + number -- which uniquely identify the procedure to be called. + Program numbers are administered by some central authority (like + Sun). Once implementors have a program number, they can implement + their remote program; the first implementation would most likely have + the version number 1. Because most new protocols evolve, a version + field of the call message identifies which version of the protocol + the caller is using. Version numbers make speaking old and new + protocols through the same server process possible. + + The procedure number identifies the procedure to be called. These + numbers are documented in the specific program's protocol + specification. For example, a file service's protocol specification + may state that its procedure number 5 is "read" and procedure number + 12 is "write". + + Just as remote program protocols may change over several versions, + the actual RPC message protocol could also change. Therefore, the + call message also has in it the RPC version number, which is always + equal to two for the version of RPC described here. + + The reply message to a request message has enough information to + distinguish the following error conditions: + + (1) The remote implementation of RPC does not speak protocol version + + + +Sun Microsystems [Page 5] + +RFC 1057 Remote Procedure Call, Version 2 June 1988 + + + 2. The lowest and highest supported RPC version numbers are returned. + + (2) The remote program is not available on the remote system. + + (3) The remote program does not support the requested version number. + The lowest and highest supported remote program version numbers are + returned. + + (4) The requested procedure number does not exist. (This is usually + a client side protocol or programming error.) + + (5) The parameters to the remote procedure appear to be garbage from + the server's point of view. (Again, this is usually caused by a + disagreement about the protocol between client and service.) + +7.2 Authentication + + Provisions for authentication of caller to service and vice-versa are + provided as a part of the RPC protocol. The call message has two + authentication fields, the credentials and verifier. The reply + message has one authentication field, the response verifier. The RPC + protocol specification defines all three fields to be the following + opaque type (in the eXternal Data Representation (XDR) language [9]): + + enum auth_flavor { + AUTH_NULL = 0, + AUTH_UNIX = 1, + AUTH_SHORT = 2, + AUTH_DES = 3 + /* and more to be defined */ + }; + + struct opaque_auth { + auth_flavor flavor; + opaque body<400>; + }; + + In other words, any "opaque_auth" structure is an "auth_flavor" + enumeration followed by bytes which are opaque to (uninterpreted by) + the RPC protocol implementation. + + The interpretation and semantics of the data contained within the + authentication fields is specified by individual, independent + authentication protocol specifications. (Section 9 defines the + various authentication protocols.) + + If authentication parameters were rejected, the reply message + contains information stating why they were rejected. + + + +Sun Microsystems [Page 6] + +RFC 1057 Remote Procedure Call, Version 2 June 1988 + + +7.3 Program Number Assignment + + Program numbers are given out in groups of hexadecimal 20000000 + (decimal 536870912) according to the following chart: + + 0 - 1fffffff defined by Sun + 20000000 - 3fffffff defined by user + 40000000 - 5fffffff transient + 60000000 - 7fffffff reserved + 80000000 - 9fffffff reserved + a0000000 - bfffffff reserved + c0000000 - dfffffff reserved + e0000000 - ffffffff reserved + + The first group is a range of numbers administered by Sun + Microsystems and should be identical for all sites. The second range + is for applications peculiar to a particular site. This range is + intended primarily for debugging new programs. When a site develops + an application that might be of general interest, that application + should be given an assigned number in the first range. The third + group is for applications that generate program numbers dynamically. + The final groups are reserved for future use, and should not be used. + +7.4 Other Uses of the RPC Protocol + + The intended use of this protocol is for calling remote procedures. + Normally, each call message is matched with a reply message. + However, the protocol itself is a message-passing protocol with which + other (non-procedure call) protocols can be implemented. Sun + currently uses, or perhaps abuses, the RPC message protocol for the + batching (or pipelining) and broadcast remote procedure calls. + +7.4.1 Batching + + Batching is useful when a client wishes to send an arbitrarily large + sequence of call messages to a server. Batching typically uses + reliable byte stream protocols (like TCP) for its transport. In the + case of batching, the client never waits for a reply from the server, + and the server does not send replies to batch calls. A sequence of + batch calls is usually terminated by a legitimate remote procedure + call operation in order to flush the pipeline and get positive + acknowledgement. + +7.4.2 Broadcast Remote Procedure Calls + + In broadcast protocols, the client sends a broadcast call to the + network and waits for numerous replies. This requires the use of + packet-based protocols (like UDP) as its transport protocol. Servers + + + +Sun Microsystems [Page 7] + +RFC 1057 Remote Procedure Call, Version 2 June 1988 + + + that support broadcast protocols only respond when the call is + successfully processed, and are silent in the face of errors. + Broadcast calls use the Port Mapper RPC service to achieve their + semantics. See Appendix A for more information. + +8. THE RPC MESSAGE PROTOCOL + + This section defines the RPC message protocol in the XDR data + description language [9]. + + enum msg_type { + CALL = 0, + REPLY = 1 + }; + A reply to a call message can take on two forms: The message was + either accepted or rejected. + + enum reply_stat { + MSG_ACCEPTED = 0, + MSG_DENIED = 1 + }; + + Given that a call message was accepted, the following is the status + of an attempt to call a remote procedure. + + enum accept_stat { + SUCCESS = 0, /* RPC executed successfully */ + PROG_UNAVAIL = 1, /* remote hasn't exported program */ + PROG_MISMATCH = 2, /* remote can't support version # */ + PROC_UNAVAIL = 3, /* program can't support procedure */ + GARBAGE_ARGS = 4 /* procedure can't decode params */ + }; + + Reasons why a call message was rejected: + + enum reject_stat { + RPC_MISMATCH = 0, /* RPC version number != 2 */ + AUTH_ERROR = 1 /* remote can't authenticate caller */ + }; + + + + + + + + + + + + +Sun Microsystems [Page 8] + +RFC 1057 Remote Procedure Call, Version 2 June 1988 + + + Why authentication failed: + + enum auth_stat { + AUTH_BADCRED = 1, /* bad credentials (seal broken) */ + AUTH_REJECTEDCRED = 2, /* client must begin new session */ + AUTH_BADVERF = 3, /* bad verifier (seal broken) */ + AUTH_REJECTEDVERF = 4, /* verifier expired or replayed */ + AUTH_TOOWEAK = 5 /* rejected for security reasons */ + }; + + The RPC message: + + All messages start with a transaction identifier, xid, followed by a + two-armed discriminated union. The union's discriminant is a + msg_type which switches to one of the two types of the message. The + xid of a REPLY message always matches that of the initiating CALL + message. NB: The xid field is only used for clients matching reply + messages with call messages or for servers detecting retransmissions; + the service side cannot treat this id as any type of sequence number. + + struct rpc_msg { + unsigned int xid; + union switch (msg_type mtype) { + case CALL: + call_body cbody; + case REPLY: + reply_body rbody; + } body; + }; + + Body of an RPC call: + + In version 2 of the RPC protocol specification, rpcvers must be equal + to 2. The fields prog, vers, and proc specify the remote program, + its version number, and the procedure within the remote program to be + called. After these fields are two authentication parameters: cred + (authentication credentials) and verf (authentication verifier). The + two authentication parameters are followed by the parameters to the + remote procedure, which are specified by the specific program + protocol. + + + + + + + + + + + +Sun Microsystems [Page 9] + +RFC 1057 Remote Procedure Call, Version 2 June 1988 + + + struct call_body { + unsigned int rpcvers; /* must be equal to two (2) */ + unsigned int prog; + unsigned int vers; + unsigned int proc; + opaque_auth cred; + opaque_auth verf; + /* procedure specific parameters start here */ + }; + + Body of a reply to an RPC call: + + union reply_body switch (reply_stat stat) { + case MSG_ACCEPTED: + accepted_reply areply; + case MSG_DENIED: + rejected_reply rreply; + } reply; + + Reply to an RPC call that was accepted by the server: + + There could be an error even though the call was accepted. The first + field is an authentication verifier that the server generates in + order to validate itself to the client. It is followed by a union + whose discriminant is an enum accept_stat. The SUCCESS arm of the + union is protocol specific. The PROG_UNAVAIL, PROC_UNAVAIL, and + GARBAGE_ARGS arms of the union are void. The PROG_MISMATCH arm + specifies the lowest and highest version numbers of the remote + program supported by the server. + + + + + + + + + + + + + + + + + + + + + + +Sun Microsystems [Page 10] + +RFC 1057 Remote Procedure Call, Version 2 June 1988 + + + struct accepted_reply { + opaque_auth verf; + union switch (accept_stat stat) { + case SUCCESS: + opaque results[0]; + /* + * procedure-specific results start here + */ + case PROG_MISMATCH: + struct { + unsigned int low; + unsigned int high; + } mismatch_info; + default: + /* + * Void. Cases include PROG_UNAVAIL, PROC_UNAVAIL, + * and GARBAGE_ARGS. + */ + void; + } reply_data; + }; + + Reply to an RPC call that was rejected by the server: + + The call can be rejected for two reasons: either the server is not + running a compatible version of the RPC protocol (RPC_MISMATCH), or + the server refuses to authenticate the caller (AUTH_ERROR). In case + of an RPC version mismatch, the server returns the lowest and highest + supported RPC version numbers. In case of refused authentication, + failure status is returned. + + union rejected_reply switch (reject_stat stat) { + case RPC_MISMATCH: + struct { + unsigned int low; + unsigned int high; + } mismatch_info; + case AUTH_ERROR: + auth_stat stat; + }; + + + + + + + + + + + +Sun Microsystems [Page 11] + +RFC 1057 Remote Procedure Call, Version 2 June 1988 + + +9. AUTHENTICATION PROTOCOLS + + As previously stated, authentication parameters are opaque, but + open-ended to the rest of the RPC protocol. This section defines + some "flavors" of authentication implemented at (and supported by) + Sun. Other sites are free to invent new authentication types, with + the same rules of flavor number assignment as there is for program + number assignment. + +9.1 Null Authentication + + Often calls must be made where the client does not know its identity + or the server does not care who the client is. In this case, the + flavor value (the discriminant of the opaque_auth's union) of the RPC + message's credentials, verifier, and reply verifier is "AUTH_NULL". + The bytes of the opaque_auth's body are undefined. It is recommended + that the opaque length be zero. + +9.2 UNIX Authentication + + The client may wish to identify itself as it is identified on a + UNIX(tm) system. The value of the credential's discriminant of an + RPC call message is "AUTH_UNIX". The bytes of the credential's + opaque body encode the the following structure: + + struct auth_unix { + unsigned int stamp; + string machinename<255>; + unsigned int uid; + unsigned int gid; + unsigned int gids<16>; + }; + + The "stamp" is an arbitrary ID which the caller machine may generate. + The "machinename" is the name of the caller's machine (like + "krypton"). The "uid" is the caller's effective user ID. The "gid" + is the caller's effective group ID. The "gids" is a counted array of + groups which contain the caller as a member. The verifier + accompanying the credentials should be of "AUTH_NULL" (defined + above). Note these credentials are only unique within a particular + domain of machine names, uids, and gids. Inter-domain naming is + beyond the scope of this document. + + The value of the discriminant of the reply verifier received in the + reply message from the server may be "AUTH_NULL" or "AUTH_SHORT". In + the case of "AUTH_SHORT", the bytes of the reply verifier's string + encode an opaque structure. This new opaque structure may now be + passed to the server instead of the original "AUTH_UNIX" flavor + + + +Sun Microsystems [Page 12] + +RFC 1057 Remote Procedure Call, Version 2 June 1988 + + + credentials. The server may keep a cache which maps shorthand opaque + structures (passed back by way of an "AUTH_SHORT" style reply + verifier) to the original credentials of the caller. The caller can + save network bandwidth and server cpu cycles by using the new + credentials. + + The server may flush the shorthand opaque structure at any time. If + this happens, the remote procedure call message will be rejected due + to an authentication error. The reason for the failure will be + "AUTH_REJECTEDCRED". At this point, the client may wish to try the + original "AUTH_UNIX" style of credentials. + +9.3 DES Authentication + + UNIX authentication suffers from three major problems: + + (1) The naming is too UNIX oriented. + (2) There is no universal name, uid, and gid space. + (3) There is no verifier, so credentials can easily be faked. + + DES authentication attempts to address these problems. + +9.3.1 Naming + + The first problem is handled by addressing the client by a simple + string of characters instead of by an operating system specific + integer. This string of characters is known as the "netname" or + network name of the client. The server is not allowed to interpret + the contents of the client's name in any other way except to identify + the client. Thus, netnames should be unique for every client in the + Internet. + + It is up to each operating system's implementation of DES + authentication to generate netnames for its users that insure this + uniqueness when they call upon remote servers. Operating systems + already know how to distinguish users local to their systems. It is + usually a simple matter to extend this mechanism to the network. For + example, a UNIX user at Sun with a user ID of 515 might be assigned + the following netname: "unix.515@sun.com". This netname contains + three items that serve to insure it is unique. Going backwards, + there is only one naming domain called "sun.com" in the Internet. + Within this domain, there is only one UNIX user with user ID 515. + However, there may be another user on another operating system, for + example VMS, within the same naming domain that, by coincidence, + happens to have the same user ID. To insure that these two users can + be distinguished we add the operating system name. So one user is + "unix.515@sun.com" and the other is "vms.515@sun.com". + + + + +Sun Microsystems [Page 13] + +RFC 1057 Remote Procedure Call, Version 2 June 1988 + + + The first field is actually a naming method rather than an operating + system name. It happens that today there is almost a one-to-one + correspondence between naming methods and operating systems. If the + world could agree on a naming standard, the first field could be the + name of that standard, instead of an operating system name. + +9.3.2 DES Authentication Verifiers + + Unlike UNIX authentication, DES authentication does have a verifier + so the server can validate the client's credential (and vice-versa). + The contents of this verifier is primarily an encrypted timestamp. + The server can decrypt this timestamp, and if it is close to the real + time, then the client must have encrypted it correctly. The only way + the client could encrypt it correctly is to know the "conversation + key" of the RPC session. And if the client knows the conversation + key, then it must be the real client. + + The conversation key is a DES [5] key which the client generates and + passes to the server in its first RPC call. The conversation key is + encrypted using a public key scheme in this first transaction. The + particular public key scheme used in DES authentication is Diffie- + Hellman [3] with 192-bit keys. The details of this encryption method + are described later. + + The client and the server need the same notion of the current time in + order for all of this to work, perhaps by using the Network Time + Protocol [4]. If network time synchronization cannot be guaranteed, + then the client can determine the server's time before beginning the + conversation using a simpler time request protocol. + + The way a server determines if a client timestamp is valid is + somewhat complicated. For any other transaction but the first, the + server just checks for two things: + + (1) the timestamp is greater than the one previously seen from the + same client. + (2) the timestamp has not expired. + + A timestamp is expired if the server's time is later than the sum of + the client's timestamp plus what is known as the client's "window". + The "window" is a number the client passes (encrypted) to the server + in its first transaction. You can think of it as a lifetime for the + credential. + + This explains everything but the first transaction. In the first + transaction, the server checks only that the timestamp has not + expired. If this was all that was done though, then it would be + quite easy for the client to send random data in place of the + + + +Sun Microsystems [Page 14] + +RFC 1057 Remote Procedure Call, Version 2 June 1988 + + + timestamp with a fairly good chance of succeeding. As an added + check, the client sends an encrypted item in the first transaction + known as the "window verifier" which must be equal to the window + minus 1, or the server will reject the credential. + + The client too must check the verifier returned from the server to be + sure it is legitimate. The server sends back to the client the + encrypted timestamp it received from the client, minus one second. + If the client gets anything different than this, it will reject it. + +9.3.3 Nicknames and Clock Synchronization + + After the first transaction, the server's DES authentication + subsystem returns in its verifier to the client an integer "nickname" + which the client may use in its further transactions instead of + passing its netname, encrypted DES key and window every time. The + nickname is most likely an index into a table on the server which + stores for each client its netname, decrypted DES key and window. + + Though they originally were synchronized, the client's and server's + clocks can get out of sync again. When this happens the client RPC + subsystem most likely will get back "RPC_AUTHERROR" at which point it + should resynchronize. + + A client may still get the "RPC_AUTHERROR" error even though it is + synchronized with the server. The reason is that the server's + nickname table is a limited size, and it may flush entries whenever + it wants. A client should resend its original credential in this + case and the server will give it a new nickname. If a server + crashes, the entire nickname table gets flushed, and all clients will + have to resend their original credentials. + +9.3.4 DES Authentication Protocol Specification + + There are two kinds of credentials: one in which the client uses its + full network name, and one in which it uses its "nickname" (just an + unsigned integer) given to it by the server. The client must use its + fullname in its first transaction with the server, in which the + server will return to the client its nickname. The client may use + its nickname in all further transactions with the server. There is no + requirement to use the nickname, but it is wise to use it for + performance reasons. + + enum authdes_namekind { + ADN_FULLNAME = 0, + ADN_NICKNAME = 1 + }; + + + + +Sun Microsystems [Page 15] + +RFC 1057 Remote Procedure Call, Version 2 June 1988 + + + A 64-bit block of encrypted DES data: + + typedef opaque des_block[8]; + + Maximum length of a network user's name: + + const MAXNETNAMELEN = 255; + + A fullname contains the network name of the client, an encrypted + conversation key and the window. The window is actually a lifetime + for the credential. If the time indicated in the verifier timestamp + plus the window has past, then the server should expire the request + and not grant it. To insure that requests are not replayed, the + server should insist that timestamps are greater than the previous + one seen, unless it is the first transaction. In the first + transaction, the server checks instead that the window verifier is + one less than the window. + + struct authdes_fullname { + string name; /* name of client */ + des_block key; /* PK encrypted conversation key */ + opaque window[4]; /* encrypted window */ + }; + + A credential is either a fullname or a nickname: + + union authdes_cred switch (authdes_namekind adc_namekind) { + case ADN_FULLNAME: + authdes_fullname adc_fullname; + case ADN_NICKNAME: + int adc_nickname; + }; + + A timestamp encodes the time since midnight, March 1, 1970. + + struct timestamp { + unsigned int seconds; /* seconds */ + unsigned int useconds; /* and microseconds */ + }; + + Verifier: client variety. + + The window verifier is only used in the first transaction. In + conjunction with a fullname credential, these items are packed into + the following structure before being encrypted: + + + + + + +Sun Microsystems [Page 16] + +RFC 1057 Remote Procedure Call, Version 2 June 1988 + + + struct { + adv_timestamp; -- one DES block + adc_fullname.window; -- one half DES block + adv_winverf; -- one half DES block + } + + This structure is encrypted using CBC mode encryption with an input + vector of zero. All other encryptions of timestamps use ECB mode + encryption. + + struct authdes_verf_clnt { + des_block adv_timestamp; /* encrypted timestamp */ + opaque adv_winverf[4]; /* encrypted window verifier */ + }; + + Verifier: server variety. + + The server returns (encrypted) the same timestamp the client gave it + minus one second. It also tells the client its nickname to be used + in future transactions (unencrypted). + + struct authdes_verf_svr { + des_block adv_timeverf; /* encrypted verifier */ + int adv_nickname; /* new nickname for client */ + }; + +9.3.5 Diffie-Hellman Encryption + + In this scheme, there are two constants "BASE" and "MODULUS" [3]. + The particular values Sun has chosen for these for the DES + authentication protocol are: + + const BASE = 3; + const MODULUS = "d4a0ba0250b6fd2ec626e7efd637df76c716e22d0944b88b" + + The way this scheme works is best explained by an example. Suppose + there are two people "A" and "B" who want to send encrypted messages + to each other. So, A and B both generate "secret" keys at random + which they do not reveal to anyone. Let these keys be represented as + SK(A) and SK(B). They also publish in a public directory their + "public" keys. These keys are computed as follows: + + PK(A) = ( BASE ** SK(A) ) mod MODULUS + PK(B) = ( BASE ** SK(B) ) mod MODULUS + + The "**" notation is used here to represent exponentiation. Now, both + A and B can arrive at the "common" key between them, represented here + as CK(A, B), without revealing their secret keys. + + + +Sun Microsystems [Page 17] + +RFC 1057 Remote Procedure Call, Version 2 June 1988 + + + A computes: + + CK(A, B) = ( PK(B) ** SK(A)) mod MODULUS + + while B computes: + + CK(A, B) = ( PK(A) ** SK(B)) mod MODULUS + + These two can be shown to be equivalent: + + (PK(B) ** SK(A)) mod MODULUS = (PK(A) ** SK(B)) mod MODULUS + + We drop the "mod MODULUS" parts and assume modulo arithmetic to + simplify things: + + PK(B) ** SK(A) = PK(A) ** SK(B) + + Then, replace PK(B) by what B computed earlier and likewise for PK(A). + + ((BASE ** SK(B)) ** SK(A) = (BASE ** SK(A)) ** SK(B) + + which leads to: + + BASE ** (SK(A) * SK(B)) = BASE ** (SK(A) * SK(B)) + + This common key CK(A, B) is not used to encrypt the timestamps used + in the protocol. Rather, it is used only to encrypt a conversation + key which is then used to encrypt the timestamps. The reason for + doing this is to use the common key as little as possible, for fear + that it could be broken. Breaking the conversation key is a far less + serious offense, since conversations are relatively short-lived. + + The conversation key is encrypted using 56-bit DES keys, yet the + common key is 192 bits. To reduce the number of bits, 56 bits are + selected from the common key as follows. The middle-most 8-bytes are + selected from the common key, and then parity is added to the lower + order bit of each byte, producing a 56-bit key with 8 bits of parity. + +10. RECORD MARKING STANDARD + + When RPC messages are passed on top of a byte stream transport + protocol (like TCP), it is necessary to delimit one message from + another in order to detect and possibly recover from protocol errors. + This is called record marking (RM). Sun uses this RM/TCP/IP + transport for passing RPC messages on TCP streams. One RPC message + fits into one RM record. + + A record is composed of one or more record fragments. A record + + + +Sun Microsystems [Page 18] + +RFC 1057 Remote Procedure Call, Version 2 June 1988 + + + fragment is a four-byte header followed by 0 to (2**31) - 1 bytes of + fragment data. The bytes encode an unsigned binary number; as with + XDR integers, the byte order is from highest to lowest. The number + encodes two values -- a boolean which indicates whether the fragment + is the last fragment of the record (bit value 1 implies the fragment + is the last fragment) and a 31-bit unsigned binary value which is the + length in bytes of the fragment's data. The boolean value is the + highest-order bit of the header; the length is the 31 low-order bits. + (Note that this record specification is NOT in XDR standard form!) + +11. THE RPC LANGUAGE + + Just as there was a need to describe the XDR data-types in a formal + language, there is also need to describe the procedures that operate + on these XDR data-types in a formal language as well. The RPC + Language is an extension to the XDR language, with the addition of + "program", "procedure", and "version" declarations. The following + example is used to describe the essence of the language. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Sun Microsystems [Page 19] + +RFC 1057 Remote Procedure Call, Version 2 June 1988 + + +11.1 An Example Service Described in the RPC Language + + Here is an example of the specification of a simple ping program. + + program PING_PROG { + /* + * Latest and greatest version + */ + version PING_VERS_PINGBACK { + void + PINGPROC_NULL(void) = 0; + + /* + * Ping the client, return the round-trip time + * (in microseconds). Returns -1 if the operation + * timed out. + */ + int + PINGPROC_PINGBACK(void) = 1; + } = 2; + + /* + * Original version + */ + version PING_VERS_ORIG { + void + PINGPROC_NULL(void) = 0; + } = 1; + } = 1; + + const PING_VERS = 2; /* latest version */ + + The first version described is PING_VERS_PINGBACK with two + procedures, PINGPROC_NULL and PINGPROC_PINGBACK. PINGPROC_NULL takes + no arguments and returns no results, but it is useful for computing + round-trip times from the client to the server and back again. By + convention, procedure 0 of any RPC protocol should have the same + semantics, and never require any kind of authentication. The second + procedure is used for the client to have the server do a reverse ping + operation back to the client, and it returns the amount of time (in + microseconds) that the operation used. The next version, + PING_VERS_ORIG, is the original version of the protocol and it does + not contain PINGPROC_PINGBACK procedure. It is useful for + compatibility with old client programs, and as this program matures + it may be dropped from the protocol entirely. + + + + + + +Sun Microsystems [Page 20] + +RFC 1057 Remote Procedure Call, Version 2 June 1988 + + +11.2 The RPC Language Specification + + The RPC language is identical to the XDR language defined in RFC + 1014, except for the added definition of a "program-def" described + below. + + program-def: + "program" identifier "{" + version-def + version-def * + "}" "=" constant ";" + + version-def: + "version" identifier "{" + procedure-def + procedure-def * + "}" "=" constant ";" + + procedure-def: + type-specifier identifier "(" type-specifier + ("," type-specifier )* ")" "=" constant ";" + +11.3 Syntax Notes + + (1) The following keywords are added and cannot be used as + identifiers: "program" and "version"; + + (2) A version name cannot occur more than once within the scope of a + program definition. Nor can a version number occur more than once + within the scope of a program definition. + + (3) A procedure name cannot occur more than once within the scope of + a version definition. Nor can a procedure number occur more than once + within the scope of version definition. + + (4) Program identifiers are in the same name space as constant and + type identifiers. + + (5) Only unsigned constants can be assigned to programs, versions and + procedures. + + + + + + + + + + + +Sun Microsystems [Page 21] + +RFC 1057 Remote Procedure Call, Version 2 June 1988 + + +APPENDIX A: PORT MAPPER PROGRAM PROTOCOL + + The port mapper program maps RPC program and version numbers to + transport-specific port numbers. This program makes dynamic binding + of remote programs possible. + + This is desirable because the range of reserved port numbers is very + small and the number of potential remote programs is very large. By + running only the port mapper on a reserved port, the port numbers of + other remote programs can be ascertained by querying the port mapper. + + The port mapper also aids in broadcast RPC. A given RPC program will + usually have different port number bindings on different machines, so + there is no way to directly broadcast to all of these programs. The + port mapper, however, does have a fixed port number. So, to + broadcast to a given program, the client actually sends its message + to the port mapper located at the broadcast address. Each port mapper + that picks up the broadcast then calls the local service specified by + the client. When the port mapper gets the reply from the local + service, it sends the reply on back to the client. + +A.1 Port Mapper Protocol Specification (in RPC Language) + + const PMAP_PORT = 111; /* portmapper port number */ + + A mapping of (program, version, protocol) to port number: + + struct mapping { + unsigned int prog; + unsigned int vers; + unsigned int prot; + unsigned int port; + }; + + Supported values for the "prot" field: + + const IPPROTO_TCP = 6; /* protocol number for TCP/IP */ + const IPPROTO_UDP = 17; /* protocol number for UDP/IP */ + + A list of mappings: + + struct *pmaplist { + mapping map; + pmaplist next; + }; + + + + + + +Sun Microsystems [Page 22] + +RFC 1057 Remote Procedure Call, Version 2 June 1988 + + + Arguments to callit: + + struct call_args { + unsigned int prog; + unsigned int vers; + unsigned int proc; + opaque args<>; + }; + + Results of callit: + + struct call_result { + unsigned int port; + opaque res<>; + }; + + Port mapper procedures: + + program PMAP_PROG { + version PMAP_VERS { + void + PMAPPROC_NULL(void) = 0; + + bool + PMAPPROC_SET(mapping) = 1; + + bool + PMAPPROC_UNSET(mapping) = 2; + + unsigned int + PMAPPROC_GETPORT(mapping) = 3; + + pmaplist + PMAPPROC_DUMP(void) = 4; + + call_result + PMAPPROC_CALLIT(call_args) = 5; + } = 2; + } = 100000; + +A.2 Port Mapper Operation + + The portmapper program currently supports two protocols (UDP and + TCP). The portmapper is contacted by talking to it on assigned port + number 111 (SUNRPC) on either of these protocols. + + + + + + +Sun Microsystems [Page 23] + +RFC 1057 Remote Procedure Call, Version 2 June 1988 + + + The following is a description of each of the portmapper procedures: + + PMAPPROC_NULL: + + This procedure does no work. By convention, procedure zero of any + protocol takes no parameters and returns no results. + + PMAPPROC_SET: + + When a program first becomes available on a machine, it registers + itself with the port mapper program on the same machine. The program + passes its program number "prog", version number "vers", transport + protocol number "prot", and the port "port" on which it awaits + service request. The procedure returns a boolean reply whose value + is "TRUE" if the procedure successfully established the mapping and + "FALSE" otherwise. The procedure refuses to establish a mapping if + one already exists for the tuple "(prog, vers, prot)". + + PMAPPROC_UNSET: + + When a program becomes unavailable, it should unregister itself with + the port mapper program on the same machine. The parameters and + results have meanings identical to those of "PMAPPROC_SET". The + protocol and port number fields of the argument are ignored. + + PMAPPROC_GETPORT: + + Given a program number "prog", version number "vers", and transport + protocol number "prot", this procedure returns the port number on + which the program is awaiting call requests. A port value of zeros + means the program has not been registered. The "port" field of the + argument is ignored. + + PMAPPROC_DUMP: + + This procedure enumerates all entries in the port mapper's database. + The procedure takes no parameters and returns a list of program, + version, protocol, and port values. + + PMAPPROC_CALLIT: + + This procedure allows a client to call another remote procedure on + the same machine without knowing the remote procedure's port number. + It is intended for supporting broadcasts to arbitrary remote programs + via the well-known port mapper's port. The parameters "prog", + "vers", "proc", and the bytes of "args" are the program number, + version number, procedure number, and parameters of the remote + procedure. Note: + + + +Sun Microsystems [Page 24] + +RFC 1057 Remote Procedure Call, Version 2 June 1988 + + + (1) This procedure only sends a reply if the procedure was + successfully executed and is silent (no reply) otherwise. + + (2) The port mapper communicates with the remote program using UDP + only. + + The procedure returns the remote program's port number, and the reply + is the reply of the remote procedure. + +REFERENCES + + [1] Birrell, A. D. & Nelson, B. J., "Implementing Remote Procedure + Calls", XEROX CSL-83-7, October 1983. + + [2] Cheriton, D., "VMTP: Versatile Message Transaction Protocol", + Preliminary Version 0.3, Stanford University, January 1987. + + [3] Diffie & Hellman, "New Directions in Cryptography", IEEE + Transactions on Information Theory IT-22, November 1976. + + [4] Mills, D., "Network Time Protocol", RFC-958, M/A-COM Linkabit, + September 1985. + + [5] National Bureau of Standards, "Data Encryption Standard", Federal + Information Processing Standards Publication 46, January 1977. + + [6] Postel, J., "Transmission Control Protocol - DARPA Internet + Program Protocol Specification", RFC-793, Information Sciences + Institute, September 1981. + + [7] Postel, J., "User Datagram Protocol", RFC-768, Information + Sciences Institute, August 1980. + + [8] Reynolds, J., and Postel, J., "Assigned Numbers", RFC-1010, + Information Sciences Institute, May 1987. + + [9] Sun Microsystems, "XDR: External Data Representation Standard", + RFC-1014, June 1987. + + + + + + + + + + + + + +Sun Microsystems [Page 25] diff --git a/src/rpc/__tests__/rfc1831.txt b/src/rpc/__tests__/rfc1831.txt new file mode 100644 index 00000000..9a23393c --- /dev/null +++ b/src/rpc/__tests__/rfc1831.txt @@ -0,0 +1,1011 @@ + + + + + + +Network Working Group R. Srinivasan +Request for Comments: 1831 Sun Microsystems +Category: Standards Track August 1995 + + + RPC: Remote Procedure Call Protocol Specification Version 2 + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +ABSTRACT + + This document describes the ONC Remote Procedure Call (ONC RPC + Version 2) protocol as it is currently deployed and accepted. "ONC" + stands for "Open Network Computing". + +TABLE OF CONTENTS + + 1. INTRODUCTION 2 + 2. TERMINOLOGY 2 + 3. THE RPC MODEL 2 + 4. TRANSPORTS AND SEMANTICS 4 + 5. BINDING AND RENDEZVOUS INDEPENDENCE 5 + 6. AUTHENTICATION 5 + 7. RPC PROTOCOL REQUIREMENTS 5 + 7.1 RPC Programs and Procedures 6 + 7.2 Authentication 7 + 7.3 Program Number Assignment 8 + 7.4 Other Uses of the RPC Protocol 8 + 7.4.1 Batching 8 + 7.4.2 Broadcast Remote Procedure Calls 8 + 8. THE RPC MESSAGE PROTOCOL 9 + 9. AUTHENTICATION PROTOCOLS 12 + 9.1 Null Authentication 13 + 10. RECORD MARKING STANDARD 13 + 11. THE RPC LANGUAGE 13 + 11.1 An Example Service Described in the RPC Language 13 + 11.2 The RPC Language Specification 14 + 11.3 Syntax Notes 15 + APPENDIX A: SYSTEM AUTHENTICATION 16 + REFERENCES 17 + Security Considerations 18 + Author's Address 18 + + + +Srinivasan Standards Track [Page 1] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +1. INTRODUCTION + + This document specifies version two of the message protocol used in + ONC Remote Procedure Call (RPC). The message protocol is specified + with the eXternal Data Representation (XDR) language [9]. This + document assumes that the reader is familiar with XDR. It does not + attempt to justify remote procedure calls systems or describe their + use. The paper by Birrell and Nelson [1] is recommended as an + excellent background for the remote procedure call concept. + +2. TERMINOLOGY + + This document discusses clients, calls, servers, replies, services, + programs, procedures, and versions. Each remote procedure call has + two sides: an active client side that makes the call to a server, + which sends back a reply. A network service is a collection of one + or more remote programs. A remote program implements one or more + remote procedures; the procedures, their parameters, and results are + documented in the specific program's protocol specification. A + server may support more than one version of a remote program in order + to be compatible with changing protocols. + + For example, a network file service may be composed of two programs. + One program may deal with high-level applications such as file system + access control and locking. The other may deal with low-level file + input and output and have procedures like "read" and "write". A + client of the network file service would call the procedures + associated with the two programs of the service on behalf of the + client. + + The terms client and server only apply to a particular transaction; a + particular hardware entity (host) or software entity (process or + program) could operate in both roles at different times. For + example, a program that supplies remote execution service could also + be a client of a network file service. + +3. THE RPC MODEL + + The ONC RPC protocol is based on the remote procedure call model, + which is similar to the local procedure call model. In the local + case, the caller places arguments to a procedure in some well- + specified location (such as a register window). It then transfers + control to the procedure, and eventually regains control. At that + point, the results of the procedure are extracted from the well- + specified location, and the caller continues execution. + + + + + + +Srinivasan Standards Track [Page 2] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + The remote procedure call model is similar. One thread of control + logically winds through two processes: the caller's process, and a + server's process. The caller process first sends a call message to + the server process and waits (blocks) for a reply message. The call + message includes the procedure's parameters, and the reply message + includes the procedure's results. Once the reply message is + received, the results of the procedure are extracted, and caller's + execution is resumed. + + On the server side, a process is dormant awaiting the arrival of a + call message. When one arrives, the server process extracts the + procedure's parameters, computes the results, sends a reply message, + and then awaits the next call message. + + In this model, only one of the two processes is active at any given + time. However, this model is only given as an example. The ONC RPC + protocol makes no restrictions on the concurrency model implemented, + and others are possible. For example, an implementation may choose + to have RPC calls be asynchronous, so that the client may do useful + work while waiting for the reply from the server. Another + possibility is to have the server create a separate task to process + an incoming call, so that the original server can be free to receive + other requests. + + There are a few important ways in which remote procedure calls differ + from local procedure calls: + + 1. Error handling: failures of the remote server or network must + be handled when using remote procedure calls. + + 2. Global variables and side-effects: since the server does not + have access to the client's address space, hidden arguments cannot + be passed as global variables or returned as side effects. + + 3. Performance: remote procedures usually operate one or more + orders of magnitude slower than local procedure calls. + + 4. Authentication: since remote procedure calls can be transported + over unsecured networks, authentication may be necessary. + Authentication prevents one entity from masquerading as some other + entity. + + The conclusion is that even though there are tools to automatically + generate client and server libraries for a given service, protocols + must still be designed carefully. + + + + + + +Srinivasan Standards Track [Page 3] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +4. TRANSPORTS AND SEMANTICS + + The RPC protocol can be implemented on several different transport + protocols. The RPC protocol does not care how a message is passed + from one process to another, but only with specification and + interpretation of messages. However, the application may wish to + obtain information about (and perhaps control over) the transport + layer through an interface not specified in this document. For + example, the transport protocol may impose a restriction on the + maximum size of RPC messages, or it may be stream-oriented like TCP + with no size limit. The client and server must agree on their + transport protocol choices. + + It is important to point out that RPC does not try to implement any + kind of reliability and that the application may need to be aware of + the type of transport protocol underneath RPC. If it knows it is + running on top of a reliable transport such as TCP [6], then most of + the work is already done for it. On the other hand, if it is running + on top of an unreliable transport such as UDP [7], it must implement + its own time-out, retransmission, and duplicate detection policies as + the RPC protocol does not provide these services. + + Because of transport independence, the RPC protocol does not attach + specific semantics to the remote procedures or their execution + requirements. Semantics can be inferred from (but should be + explicitly specified by) the underlying transport protocol. For + example, consider RPC running on top of an unreliable transport such + as UDP. If an application retransmits RPC call messages after time- + outs, and does not receive a reply, it cannot infer anything about + the number of times the procedure was executed. If it does receive a + reply, then it can infer that the procedure was executed at least + once. + + A server may wish to remember previously granted requests from a + client and not regrant them in order to insure some degree of + execute-at-most-once semantics. A server can do this by taking + advantage of the transaction ID that is packaged with every RPC + message. The main use of this transaction ID is by the client RPC + entity in matching replies to calls. However, a client application + may choose to reuse its previous transaction ID when retransmitting a + call. The server may choose to remember this ID after executing a + call and not execute calls with the same ID in order to achieve some + degree of execute-at-most-once semantics. The server is not allowed + to examine this ID in any other way except as a test for equality. + + On the other hand, if using a "reliable" transport such as TCP, the + application can infer from a reply message that the procedure was + executed exactly once, but if it receives no reply message, it cannot + + + +Srinivasan Standards Track [Page 4] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + assume that the remote procedure was not executed. Note that even if + a connection-oriented protocol like TCP is used, an application still + needs time-outs and reconnection to handle server crashes. + + There are other possibilities for transports besides datagram- or + connection-oriented protocols. For example, a request-reply protocol + such as VMTP [2] is perhaps a natural transport for RPC. ONC RPC + uses both TCP and UDP transport protocols. Section 10 (RECORD + MARKING STANDARD) describes the mechanism employed by ONC RPC to + utilize a connection-oriented, stream-oriented transport such as TCP. + +5. BINDING AND RENDEZVOUS INDEPENDENCE + + The act of binding a particular client to a particular service and + transport parameters is NOT part of this RPC protocol specification. + This important and necessary function is left up to some higher-level + software. + + Implementors could think of the RPC protocol as the jump-subroutine + instruction ("JSR") of a network; the loader (binder) makes JSR + useful, and the loader itself uses JSR to accomplish its task. + Likewise, the binding software makes RPC useful, possibly using RPC + to accomplish this task. + +6. AUTHENTICATION + + The RPC protocol provides the fields necessary for a client to + identify itself to a service, and vice-versa, in each call and reply + message. Security and access control mechanisms can be built on top + of this message authentication. Several different authentication + protocols can be supported. A field in the RPC header indicates + which protocol is being used. More information on specific + authentication protocols is in section 9: "Authentication Protocols". + +7. RPC PROTOCOL REQUIREMENTS + + The RPC protocol must provide for the following: + + (1) Unique specification of a procedure to be called. + (2) Provisions for matching response messages to request messages. + (3) Provisions for authenticating the caller to service and + vice-versa. + + + + + + + + + +Srinivasan Standards Track [Page 5] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + Besides these requirements, features that detect the following are + worth supporting because of protocol roll-over errors, implementation + bugs, user error, and network administration: + + (1) RPC protocol mismatches. + (2) Remote program protocol version mismatches. + (3) Protocol errors (such as misspecification of a procedure's + parameters). + (4) Reasons why remote authentication failed. + (5) Any other reasons why the desired procedure was not called. + +7.1 RPC Programs and Procedures + + The RPC call message has three unsigned integer fields -- remote + program number, remote program version number, and remote procedure + number -- which uniquely identify the procedure to be called. + Program numbers are administered by a central authority + (rpc@sun.com). Once implementors have a program number, they can + implement their remote program; the first implementation would most + likely have the version number 1. Because most new protocols evolve, + a version field of the call message identifies which version of the + protocol the caller is using. Version numbers enable support of both + old and new protocols through the same server process. + + The procedure number identifies the procedure to be called. These + numbers are documented in the specific program's protocol + specification. For example, a file service's protocol specification + may state that its procedure number 5 is "read" and procedure number + 12 is "write". + + Just as remote program protocols may change over several versions, + the actual RPC message protocol could also change. Therefore, the + call message also has in it the RPC version number, which is always + equal to two for the version of RPC described here. + + The reply message to a request message has enough information to + distinguish the following error conditions: + + (1) The remote implementation of RPC does not support protocol + version 2. The lowest and highest supported RPC version numbers + are returned. + + (2) The remote program is not available on the remote system. + + (3) The remote program does not support the requested version + number. The lowest and highest supported remote program version + numbers are returned. + + + + +Srinivasan Standards Track [Page 6] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + (4) The requested procedure number does not exist. (This is + usually a client side protocol or programming error.) + + (5) The parameters to the remote procedure appear to be garbage + from the server's point of view. (Again, this is usually caused + by a disagreement about the protocol between client and service.) + +7.2 Authentication + + Provisions for authentication of caller to service and vice-versa are + provided as a part of the RPC protocol. The call message has two + authentication fields, the credential and verifier. The reply + message has one authentication field, the response verifier. The RPC + protocol specification defines all three fields to be the following + opaque type (in the eXternal Data Representation (XDR) language [9]): + + enum auth_flavor { + AUTH_NONE = 0, + AUTH_SYS = 1, + AUTH_SHORT = 2 + /* and more to be defined */ + }; + + struct opaque_auth { + auth_flavor flavor; + opaque body<400>; + }; + + In other words, any "opaque_auth" structure is an "auth_flavor" + enumeration followed by up to 400 bytes which are opaque to + (uninterpreted by) the RPC protocol implementation. + + The interpretation and semantics of the data contained within the + authentication fields is specified by individual, independent + authentication protocol specifications. (Section 9 defines the + various authentication protocols.) + + If authentication parameters were rejected, the reply message + contains information stating why they were rejected. + + + + + + + + + + + + +Srinivasan Standards Track [Page 7] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +7.3 Program Number Assignment + + Program numbers are given out in groups of hexadecimal 20000000 + (decimal 536870912) according to the following chart: + + 0 - 1fffffff defined by rpc@sun.com + 20000000 - 3fffffff defined by user + 40000000 - 5fffffff transient + 60000000 - 7fffffff reserved + 80000000 - 9fffffff reserved + a0000000 - bfffffff reserved + c0000000 - dfffffff reserved + e0000000 - ffffffff reserved + + The first group is a range of numbers administered by rpc@sun.com and + should be identical for all sites. The second range is for + applications peculiar to a particular site. This range is intended + primarily for debugging new programs. When a site develops an + application that might be of general interest, that application + should be given an assigned number in the first range. Application + developers may apply for blocks of RPC program numbers in the first + range by sending electronic mail to "rpc@sun.com". The third group + is for applications that generate program numbers dynamically. The + final groups are reserved for future use, and should not be used. + +7.4 Other Uses of the RPC Protocol + + The intended use of this protocol is for calling remote procedures. + Normally, each call message is matched with a reply message. + However, the protocol itself is a message-passing protocol with which + other (non-procedure call) protocols can be implemented. + +7.4.1 Batching + + Batching is useful when a client wishes to send an arbitrarily large + sequence of call messages to a server. Batching typically uses + reliable byte stream protocols (like TCP) for its transport. In the + case of batching, the client never waits for a reply from the server, + and the server does not send replies to batch calls. A sequence of + batch calls is usually terminated by a legitimate remote procedure + call operation in order to flush the pipeline and get positive + acknowledgement. + +7.4.2 Broadcast Remote Procedure Calls + + In broadcast protocols, the client sends a broadcast call to the + network and waits for numerous replies. This requires the use of + packet-based protocols (like UDP) as its transport protocol. Servers + + + +Srinivasan Standards Track [Page 8] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + that support broadcast protocols usually respond only when the call + is successfully processed and are silent in the face of errors, but + this varies with the application. + + The principles of broadcast RPC also apply to multicasting - an RPC + request can be sent to a multicast address. + +8. THE RPC MESSAGE PROTOCOL + + This section defines the RPC message protocol in the XDR data + description language [9]. + + enum msg_type { + CALL = 0, + REPLY = 1 + }; + + A reply to a call message can take on two forms: The message was + either accepted or rejected. + + enum reply_stat { + MSG_ACCEPTED = 0, + MSG_DENIED = 1 + }; + + Given that a call message was accepted, the following is the status + of an attempt to call a remote procedure. + + enum accept_stat { + SUCCESS = 0, /* RPC executed successfully */ + PROG_UNAVAIL = 1, /* remote hasn't exported program */ + PROG_MISMATCH = 2, /* remote can't support version # */ + PROC_UNAVAIL = 3, /* program can't support procedure */ + GARBAGE_ARGS = 4, /* procedure can't decode params */ + SYSTEM_ERR = 5 /* errors like memory allocation failure */ + }; + + Reasons why a call message was rejected: + + enum reject_stat { + RPC_MISMATCH = 0, /* RPC version number != 2 */ + AUTH_ERROR = 1 /* remote can't authenticate caller */ + }; + + Why authentication failed: + + enum auth_stat { + AUTH_OK = 0, /* success */ + + + +Srinivasan Standards Track [Page 9] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + /* + * failed at remote end + */ + AUTH_BADCRED = 1, /* bad credential (seal broken) */ + AUTH_REJECTEDCRED = 2, /* client must begin new session */ + AUTH_BADVERF = 3, /* bad verifier (seal broken) */ + AUTH_REJECTEDVERF = 4, /* verifier expired or replayed */ + AUTH_TOOWEAK = 5, /* rejected for security reasons */ + /* + * failed locally + */ + AUTH_INVALIDRESP = 6, /* bogus response verifier */ + AUTH_FAILED = 7 /* reason unknown */ + }; + + The RPC message: + + All messages start with a transaction identifier, xid, followed by a + two-armed discriminated union. The union's discriminant is a + msg_type which switches to one of the two types of the message. The + xid of a REPLY message always matches that of the initiating CALL + message. NB: The xid field is only used for clients matching reply + messages with call messages or for servers detecting retransmissions; + the service side cannot treat this id as any type of sequence number. + + struct rpc_msg { + unsigned int xid; + union switch (msg_type mtype) { + case CALL: + call_body cbody; + case REPLY: + reply_body rbody; + } body; + }; + + Body of an RPC call: + + In version 2 of the RPC protocol specification, rpcvers must be equal + to 2. The fields prog, vers, and proc specify the remote program, + its version number, and the procedure within the remote program to be + called. After these fields are two authentication parameters: cred + (authentication credential) and verf (authentication verifier). The + two authentication parameters are followed by the parameters to the + remote procedure, which are specified by the specific program + protocol. + + The purpose of the authentication verifier is to validate the + authentication credential. Note that these two items are + + + +Srinivasan Standards Track [Page 10] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + historically separate, but are always used together as one logical + entity. + + struct call_body { + unsigned int rpcvers; /* must be equal to two (2) */ + unsigned int prog; + unsigned int vers; + unsigned int proc; + opaque_auth cred; + opaque_auth verf; + /* procedure specific parameters start here */ + }; + + Body of a reply to an RPC call: + + union reply_body switch (reply_stat stat) { + case MSG_ACCEPTED: + accepted_reply areply; + case MSG_DENIED: + rejected_reply rreply; + } reply; + + Reply to an RPC call that was accepted by the server: + + There could be an error even though the call was accepted. The first + field is an authentication verifier that the server generates in + order to validate itself to the client. It is followed by a union + whose discriminant is an enum accept_stat. The SUCCESS arm of the + union is protocol specific. The PROG_UNAVAIL, PROC_UNAVAIL, + GARBAGE_ARGS, and SYSTEM_ERR arms of the union are void. The + PROG_MISMATCH arm specifies the lowest and highest version numbers of + the remote program supported by the server. + + struct accepted_reply { + opaque_auth verf; + union switch (accept_stat stat) { + case SUCCESS: + opaque results[0]; + /* + * procedure-specific results start here + */ + case PROG_MISMATCH: + struct { + unsigned int low; + unsigned int high; + } mismatch_info; + default: + /* + + + +Srinivasan Standards Track [Page 11] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + * Void. Cases include PROG_UNAVAIL, PROC_UNAVAIL, + * GARBAGE_ARGS, and SYSTEM_ERR. + */ + void; + } reply_data; + }; + + Reply to an RPC call that was rejected by the server: + + The call can be rejected for two reasons: either the server is not + running a compatible version of the RPC protocol (RPC_MISMATCH), or + the server rejects the identity of the caller (AUTH_ERROR). In case + of an RPC version mismatch, the server returns the lowest and highest + supported RPC version numbers. In case of invalid authentication, + failure status is returned. + + union rejected_reply switch (reject_stat stat) { + case RPC_MISMATCH: + struct { + unsigned int low; + unsigned int high; + } mismatch_info; + case AUTH_ERROR: + auth_stat stat; + }; + +9. AUTHENTICATION PROTOCOLS + + As previously stated, authentication parameters are opaque, but + open-ended to the rest of the RPC protocol. This section defines two + standard "flavors" of authentication. Implementors are free to + invent new authentication types, with the same rules of flavor number + assignment as there is for program number assignment. The "flavor" + of a credential or verifier refers to the value of the "flavor" field + in the opaque_auth structure. Flavor numbers, like RPC program + numbers, are also administered centrally, and developers may assign + new flavor numbers by applying through electronic mail to + "rpc@sun.com". Credentials and verifiers are represented as variable + length opaque data (the "body" field in the opaque_auth structure). + + In this document, two flavors of authentication are described. Of + these, Null authentication (described in the next subsection) is + mandatory - it must be available in all implementations. System + authentication is described in Appendix A. It is strongly + recommended that implementors include System authentication in their + implementations. Many applications use this style of authentication, + and availability of this flavor in an implementation will enhance + interoperability. + + + +Srinivasan Standards Track [Page 12] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +9.1 Null Authentication + + Often calls must be made where the client does not care about its + identity or the server does not care who the client is. In this + case, the flavor of the RPC message's credential, verifier, and reply + verifier is "AUTH_NONE". Opaque data associated with "AUTH_NONE" is + undefined. It is recommended that the length of the opaque data be + zero. + +10. RECORD MARKING STANDARD + + When RPC messages are passed on top of a byte stream transport + protocol (like TCP), it is necessary to delimit one message from + another in order to detect and possibly recover from protocol errors. + This is called record marking (RM). One RPC message fits into one RM + record. + + A record is composed of one or more record fragments. A record + fragment is a four-byte header followed by 0 to (2**31) - 1 bytes of + fragment data. The bytes encode an unsigned binary number; as with + XDR integers, the byte order is from highest to lowest. The number + encodes two values -- a boolean which indicates whether the fragment + is the last fragment of the record (bit value 1 implies the fragment + is the last fragment) and a 31-bit unsigned binary value which is the + length in bytes of the fragment's data. The boolean value is the + highest-order bit of the header; the length is the 31 low-order bits. + (Note that this record specification is NOT in XDR standard form!) + +11. THE RPC LANGUAGE + + Just as there was a need to describe the XDR data-types in a formal + language, there is also need to describe the procedures that operate + on these XDR data-types in a formal language as well. The RPC + Language is an extension to the XDR language, with the addition of + "program", "procedure", and "version" declarations. The following + example is used to describe the essence of the language. + +11.1 An Example Service Described in the RPC Language + + Here is an example of the specification of a simple ping program. + + program PING_PROG { + /* + * Latest and greatest version + */ + version PING_VERS_PINGBACK { + void + PINGPROC_NULL(void) = 0; + + + +Srinivasan Standards Track [Page 13] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + /* + * Ping the client, return the round-trip time + * (in microseconds). Returns -1 if the operation + * timed out. + */ + int + PINGPROC_PINGBACK(void) = 1; + } = 2; + + /* + * Original version + */ + version PING_VERS_ORIG { + void + PINGPROC_NULL(void) = 0; + } = 1; + } = 1; + + const PING_VERS = 2; /* latest version */ + + The first version described is PING_VERS_PINGBACK with two + procedures, PINGPROC_NULL and PINGPROC_PINGBACK. PINGPROC_NULL takes + no arguments and returns no results, but it is useful for computing + round-trip times from the client to the server and back again. By + convention, procedure 0 of any RPC protocol should have the same + semantics, and never require any kind of authentication. The second + procedure is used for the client to have the server do a reverse ping + operation back to the client, and it returns the amount of time (in + microseconds) that the operation used. The next version, + PING_VERS_ORIG, is the original version of the protocol and it does + not contain PINGPROC_PINGBACK procedure. It is useful for + compatibility with old client programs, and as this program matures + it may be dropped from the protocol entirely. + +11.2 The RPC Language Specification + + The RPC language is identical to the XDR language defined in RFC + 1014, except for the added definition of a "program-def" described + below. + + program-def: + "program" identifier "{" + version-def + version-def * + "}" "=" constant ";" + + version-def: + "version" identifier "{" + + + +Srinivasan Standards Track [Page 14] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + procedure-def + procedure-def * + "}" "=" constant ";" + + procedure-def: + type-specifier identifier "(" type-specifier + ("," type-specifier )* ")" "=" constant ";" + +11.3 Syntax Notes + + (1) The following keywords are added and cannot be used as + identifiers: "program" and "version"; + + (2) A version name cannot occur more than once within the scope of a + program definition. Nor can a version number occur more than once + within the scope of a program definition. + + (3) A procedure name cannot occur more than once within the scope of + a version definition. Nor can a procedure number occur more than once + within the scope of version definition. + + (4) Program identifiers are in the same name space as constant and + type identifiers. + + (5) Only unsigned constants can be assigned to programs, versions and + procedures. + + + + + + + + + + + + + + + + + + + + + + + + + +Srinivasan Standards Track [Page 15] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +APPENDIX A: SYSTEM AUTHENTICATION + + The client may wish to identify itself, for example, as it is + identified on a UNIX(tm) system. The flavor of the client credential + is "AUTH_SYS". The opaque data constituting the credential encodes + the following structure: + + struct authsys_parms { + unsigned int stamp; + string machinename<255>; + unsigned int uid; + unsigned int gid; + unsigned int gids<16>; + }; + + The "stamp" is an arbitrary ID which the caller machine may generate. + The "machinename" is the name of the caller's machine (like + "krypton"). The "uid" is the caller's effective user ID. The "gid" + is the caller's effective group ID. The "gids" is a counted array of + groups which contain the caller as a member. The verifier + accompanying the credential should have "AUTH_NONE" flavor value + (defined above). Note this credential is only unique within a + particular domain of machine names, uids, and gids. + + The flavor value of the verifier received in the reply message from + the server may be "AUTH_NONE" or "AUTH_SHORT". In the case of + "AUTH_SHORT", the bytes of the reply verifier's string encode an + opaque structure. This new opaque structure may now be passed to the + server instead of the original "AUTH_SYS" flavor credential. The + server may keep a cache which maps shorthand opaque structures + (passed back by way of an "AUTH_SHORT" style reply verifier) to the + original credentials of the caller. The caller can save network + bandwidth and server cpu cycles by using the shorthand credential. + + The server may flush the shorthand opaque structure at any time. If + this happens, the remote procedure call message will be rejected due + to an authentication error. The reason for the failure will be + "AUTH_REJECTEDCRED". At this point, the client may wish to try the + original "AUTH_SYS" style of credential. + + It should be noted that use of this flavor of authentication does not + guarantee any security for the users or providers of a service, in + itself. The authentication provided by this scheme can be considered + legitimate only when applications using this scheme and the network + can be secured externally, and privileged transport addresses are + used for the communicating end-points (an example of this is the use + of privileged TCP/UDP ports in Unix systems - note that not all + systems enforce privileged transport address mechanisms). + + + +Srinivasan Standards Track [Page 16] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +REFERENCES + + [1] Birrell, A. D. & Nelson, B. J., "Implementing Remote Procedure + Calls", XEROX CSL-83-7, October 1983. + + [2] Cheriton, D., "VMTP: Versatile Message Transaction Protocol", + Preliminary Version 0.3, Stanford University, January 1987. + + [3] Diffie & Hellman, "New Directions in Cryptography", IEEE + Transactions on Information Theory IT-22, November 1976. + + [4] Mills, D., "Network Time Protocol", RFC 1305, UDEL, + March 1992. + + [5] National Bureau of Standards, "Data Encryption Standard", + Federal Information Processing Standards Publication 46, January + 1977. + + [6] Postel, J., "Transmission Control Protocol - DARPA Internet + Program Protocol Specification", STD 7, RFC 793, USC/Information + Sciences Institute, September 1981. + + [7] Postel, J., "User Datagram Protocol", STD 6, RFC 768, + USC/Information Sciences Institute, August 1980. + + [8] Reynolds, J., and Postel, J., "Assigned Numbers", STD 2, + RFC 1700, USC/Information Sciences Institute, October 1994. + + [9] Srinivasan, R., "XDR: External Data Representation Standard", + RFC 1832, Sun Microsystems, Inc., August 1995. + + [10] Miller, S., Neuman, C., Schiller, J., and J. Saltzer, "Section + E.2.1: Kerberos Authentication and Authorization System", + M.I.T. Project Athena, Cambridge, Massachusetts, December 21, + 1987. + + [11] Steiner, J., Neuman, C., and J. Schiller, "Kerberos: An + Authentication Service for Open Network Systems", pp. 191-202 in + Usenix Conference Proceedings, Dallas, Texas, February 1988. + + [12] Kohl, J. and C. Neuman, "The Kerberos Network Authentication + Service (V5)", RFC 1510, Digital Equipment Corporation, + USC/Information Sciences Institute, September 1993. + + + + + + + + +Srinivasan Standards Track [Page 17] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +Security Considerations + + Security issues are not discussed in this memo. + +Author's Address + + Raj Srinivasan + Sun Microsystems, Inc. + ONC Technologies + 2550 Garcia Avenue + M/S MTV-5-40 + Mountain View, CA 94043 + USA + + Phone: 415-336-2478 + Fax: 415-336-6015 + EMail: raj@eng.sun.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Srinivasan Standards Track [Page 18] + \ No newline at end of file diff --git a/src/rpc/__tests__/rfc5531.txt b/src/rpc/__tests__/rfc5531.txt new file mode 100644 index 00000000..529f9402 --- /dev/null +++ b/src/rpc/__tests__/rfc5531.txt @@ -0,0 +1,3531 @@ + + + + + + +Network Working Group R. Thurlow +Request for Comments: 5531 Sun Microsystems +Obsoletes: 1831 May 2009 +Category: Standards Track + + + RPC: Remote Procedure Call Protocol Specification Version 2 + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (c) 2009 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents in effect on the date of + publication of this document (http://trustee.ietf.org/license-info). + Please review these documents carefully, as they describe your rights + and restrictions with respect to this document. + +Abstract + + This document describes the Open Network Computing (ONC) Remote + Procedure Call (RPC) version 2 protocol as it is currently deployed + and accepted. This document obsoletes RFC 1831. + + + + + + + + + + + + + + + + + + + +Thurlow Standards Track [Page 1] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + +Table of Contents + + 1. Introduction ....................................................3 + 1.1. Requirements Language ......................................3 + 2. Changes since RFC 1831 ..........................................3 + 3. Terminology .....................................................3 + 4. The RPC Model ...................................................4 + 5. Transports and Semantics ........................................5 + 6. Binding and Rendezvous Independence .............................7 + 7. Authentication ..................................................7 + 8. RPC Protocol Requirements .......................................7 + 8.1. RPC Programs and Procedures ................................8 + 8.2. Authentication, Integrity, and Privacy .....................9 + 8.3. Program Number Assignment .................................10 + 8.4. Other Uses of the RPC Protocol ............................10 + 8.4.1. Batching ...........................................10 + 8.4.2. Broadcast Remote Procedure Calls ...................11 + 9. The RPC Message Protocol .......................................11 + 10. Authentication Protocols ......................................15 + 10.1. Null Authentication ......................................15 + 11. Record Marking Standard .......................................16 + 12. The RPC Language ..............................................16 + 12.1. An Example Service Described in the RPC Language .........17 + 12.2. The RPC Language Specification ...........................18 + 12.3. Syntax Notes .............................................18 + 13. IANA Considerations ...........................................19 + 13.1. Numbering Requests to IANA ...............................19 + 13.2. Protecting Past Assignments ..............................19 + 13.3. RPC Number Assignment ....................................19 + 13.3.1. To be assigned by IANA ............................20 + 13.3.2. Defined by Local Administrator ....................20 + 13.3.3. Transient Block ...................................20 + 13.3.4. Reserved Block ....................................21 + 13.3.5. RPC Number Sub-Blocks .............................21 + 13.4. RPC Authentication Flavor Number Assignment ..............22 + 13.4.1. Assignment Policy .................................22 + 13.4.2. Auth Flavors vs. Pseudo-Flavors ...................23 + 13.5. Authentication Status Number Assignment ..................23 + 13.5.1. Assignment Policy .................................23 + 14. Security Considerations .......................................24 + Appendix A: System Authentication .................................25 + Appendix B: Requesting RPC-Related Numbers from IANA .............26 + Appendix C: Current Number Assignments ...........................27 + Normative References .............................................62 + Informative References ...........................................62 + + + + + + +Thurlow Standards Track [Page 2] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + +1. Introduction + + This document specifies version 2 of the message protocol used in ONC + Remote Procedure Call (RPC). The message protocol is specified with + the eXternal Data Representation (XDR) language [RFC4506]. This + document assumes that the reader is familiar with XDR. It does not + attempt to justify remote procedure call systems or describe their + use. The paper by Birrell and Nelson [XRPC] is recommended as an + excellent background for the remote procedure call concept. + +1.1. Requirements Language + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + +2. Changes since RFC 1831 + + This document obsoletes [RFC1831] as the authoritative document + describing RPC, without introducing any over-the-wire protocol + changes. The main changes from RFC 1831 are: + + o Addition of an Appendix that describes how an implementor can + request new RPC program numbers, authentication flavor numbers, + and authentication status numbers from IANA, rather than from Sun + Microsystems + + o Addition of an "IANA Considerations" section that describes past + number assignment policy and how IANA is intended to assign them + in the future + + o Clarification of the RPC Language Specification to match current + usage + + o Enhancement of the "Security Considerations" section to reflect + experience with strong security flavors + + o Specification of new authentication errors that are in common use + in modern RPC implementations + + o Updates for the latest IETF intellectual property statements + +3. Terminology + + This document discusses clients, calls, servers, replies, services, + programs, procedures, and versions. Each remote procedure call has + two sides: an active client side that makes the call to a server + side, which sends back a reply. A network service is a collection of + + + +Thurlow Standards Track [Page 3] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + one or more remote programs. A remote program implements one or more + remote procedures; the procedures, their parameters, and results are + documented in the specific program's protocol specification. A + server may support more than one version of a remote program in order + to be compatible with changing protocols. + + For example, a network file service may be composed of two programs. + One program may deal with high-level applications such as file system + access control and locking. The other may deal with low-level file + input and output and have procedures like "read" and "write". A + client of the network file service would call the procedures + associated with the two programs of the service on behalf of the + client. + + The terms "client" and "server" only apply to a particular + transaction; a particular hardware entity (host) or software entity + (process or program) could operate in both roles at different times. + For example, a program that supplies remote execution service could + also be a client of a network file service. + +4. The RPC Model + + The ONC RPC protocol is based on the remote procedure call model, + which is similar to the local procedure call model. In the local + case, the caller places arguments to a procedure in some well- + specified location (such as a register window). It then transfers + control to the procedure, and eventually regains control. At that + point, the results of the procedure are extracted from the well- + specified location, and the caller continues execution. + + The remote procedure call model is similar. One thread of control + logically winds through two processes: the caller's process and a + server's process. The caller first sends a call message to the + server process and waits (blocks) for a reply message. The call + message includes the procedure's parameters, and the reply message + includes the procedure's results. Once the reply message is + received, the results of the procedure are extracted, and the + caller's execution is resumed. + + On the server side, a process is dormant awaiting the arrival of a + call message. When one arrives, the server process extracts the + procedure's parameters, computes the results, sends a reply message, + and then awaits the next call message. + + In this model, only one of the two processes is active at any given + time. However, this model is only given as an example. The ONC RPC + protocol makes no restrictions on the concurrency model implemented, + and others are possible. For example, an implementation may choose + + + +Thurlow Standards Track [Page 4] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + to have RPC calls be asynchronous so that the client may do useful + work while waiting for the reply from the server. Another + possibility is to have the server create a separate task to process + an incoming call so that the original server can be free to receive + other requests. + + There are a few important ways in which remote procedure calls differ + from local procedure calls. + + o Error handling: failures of the remote server or network must be + handled when using remote procedure calls. + + o Global variables and side effects: since the server does not have + access to the client's address space, hidden arguments cannot be + passed as global variables or returned as side effects. + + o Performance: remote procedures usually operate at one or more + orders of magnitude slower than local procedure calls. + + o Authentication: since remote procedure calls can be transported + over unsecured networks, authentication may be necessary. + Authentication prevents one entity from masquerading as some other + entity. + + The conclusion is that even though there are tools to automatically + generate client and server libraries for a given service, protocols + must still be designed carefully. + +5. Transports and Semantics + + The RPC protocol can be implemented on several different transport + protocols. The scope of the definition of the RPC protocol excludes + how a message is passed from one process to another, and includes + only the specification and interpretation of messages. However, the + application may wish to obtain information about (and perhaps control + over) the transport layer through an interface not specified in this + document. For example, the transport protocol may impose a + restriction on the maximum size of RPC messages, or it may be + stream-oriented like TCP [RFC0793] with no size limit. The client + and server must agree on their transport protocol choices. + + It is important to point out that RPC does not try to implement any + kind of reliability and that the application may need to be aware of + the type of transport protocol underneath RPC. If it knows it is + running on top of a reliable transport such as TCP, then most of the + work is already done for it. On the other hand, if it is running on + + + + + +Thurlow Standards Track [Page 5] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + top of an unreliable transport such as UDP [RFC0768], it must + implement its own time-out, retransmission, and duplicate detection + policies as the RPC protocol does not provide these services. + + Because of transport independence, the RPC protocol does not attach + specific semantics to the remote procedures or their execution + requirements. Semantics can be inferred from (but should be + explicitly specified by) the underlying transport protocol. For + example, consider RPC running on top of an unreliable transport such + as UDP. If an application retransmits RPC call messages after time- + outs, and does not receive a reply, it cannot infer anything about + the number of times the procedure was executed. If it does receive a + reply, then it can infer that the procedure was executed at least + once. + + A server may wish to remember previously granted requests from a + client and not regrant them, in order to insure some degree of + execute-at-most-once semantics. A server can do this by taking + advantage of the transaction ID that is packaged with every RPC + message. The main use of this transaction ID is by the client RPC + entity in matching replies to calls. However, a client application + may choose to reuse its previous transaction ID when retransmitting a + call. The server may choose to remember this ID after executing a + call and not execute calls with the same ID, in order to achieve some + degree of execute-at-most-once semantics. The server is not allowed + to examine this ID in any other way except as a test for equality. + + On the other hand, if using a "reliable" transport such as TCP, the + application can infer from a reply message that the procedure was + executed exactly once, but if it receives no reply message, it cannot + assume that the remote procedure was not executed. Note that even if + a connection-oriented protocol like TCP is used, an application still + needs time-outs and reconnections to handle server crashes. + + There are other possibilities for transports besides datagram- or + connection-oriented protocols. For example, a request-reply protocol + such as [VMTP] is perhaps a natural transport for RPC. ONC RPC + currently uses both TCP and UDP transport protocols. Section 11 + ("Record Marking Standard") describes the mechanism employed by ONC + RPC to utilize a connection-oriented, stream-oriented transport such + as TCP. The mechanism by which future transports having different + structural characteristics should be used to transfer ONC RPC + messages should be specified by means of a Standards Track RFC, once + such additional transports are defined. + + + + + + + +Thurlow Standards Track [Page 6] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + +6. Binding and Rendezvous Independence + + The act of binding a particular client to a particular service and + transport parameters is NOT part of this RPC protocol specification. + This important and necessary function is left up to some higher-level + software. + + Implementors could think of the RPC protocol as the jump-subroutine + instruction (JSR) of a network; the loader (binder) makes JSR useful, + and the loader itself uses JSR to accomplish its task. Likewise, the + binding software makes RPC useful, possibly using RPC to accomplish + this task. + +7. Authentication + + The RPC protocol provides the fields necessary for a client to + identify itself to a service, and vice-versa, in each call and reply + message. Security and access control mechanisms can be built on top + of this message authentication. Several different authentication + protocols can be supported. A field in the RPC header indicates + which protocol is being used. More information on specific + authentication protocols is in Section 8.2, "Authentication, + Integrity and Privacy". + +8. RPC Protocol Requirements + + The RPC protocol must provide for the following: + + o Unique specification of a procedure to be called + + o Provisions for matching response messages to request messages + + o Provisions for authenticating the caller to service and vice-versa + + Besides these requirements, features that detect the following are + worth supporting because of protocol roll-over errors, implementation + bugs, user error, and network administration: + + o RPC protocol mismatches + + o Remote program protocol version mismatches + + o Protocol errors (such as misspecification of a procedure's + parameters) + + o Reasons why remote authentication failed + + o Any other reasons why the desired procedure was not called + + + +Thurlow Standards Track [Page 7] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + +8.1. RPC Programs and Procedures + + The RPC call message has three unsigned-integer fields -- remote + program number, remote program version number, and remote procedure + number -- that uniquely identify the procedure to be called. Program + numbers are administered by a central authority (IANA). Once + implementors have a program number, they can implement their remote + program; the first implementation would most likely have the version + number 1 but MUST NOT be the number zero. Because most new protocols + evolve, a "version" field of the call message identifies which + version of the protocol the caller is using. Version numbers enable + support of both old and new protocols through the same server + process. + + The procedure number identifies the procedure to be called. These + numbers are documented in the specific program's protocol + specification. For example, a file service's protocol specification + may state that its procedure number 5 is "read" and procedure number + 12 is "write". + + Just as remote program protocols may change over several versions, + the actual RPC message protocol could also change. Therefore, the + call message also has in it the RPC version number, which is always + equal to 2 for the version of RPC described here. + + The reply message to a request message has enough information to + distinguish the following error conditions: + + o The remote implementation of RPC does not support protocol version + 2. The lowest and highest supported RPC version numbers are + returned. + + o The remote program is not available on the remote system. + + o The remote program does not support the requested version number. + The lowest and highest supported remote program version numbers + are returned. + + o The requested procedure number does not exist. (This is usually a + client-side protocol or programming error.) + + o The parameters to the remote procedure appear to be garbage from + the server's point of view. (Again, this is usually caused by a + disagreement about the protocol between client and service.) + + + + + + + +Thurlow Standards Track [Page 8] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + +8.2. Authentication, Integrity, and Privacy + + Provisions for authentication of caller to service and vice-versa are + provided as a part of the RPC protocol. The call message has two + authentication fields: the credential and the verifier. The reply + message has one authentication field: the response verifier. The RPC + protocol specification defines all three fields to be the following + opaque type (in the eXternal Data Representation (XDR) language + [RFC4506]): + + enum auth_flavor { + AUTH_NONE = 0, + AUTH_SYS = 1, + AUTH_SHORT = 2, + AUTH_DH = 3, + RPCSEC_GSS = 6 + /* and more to be defined */ + }; + + struct opaque_auth { + auth_flavor flavor; + opaque body<400>; + }; + + In other words, any "opaque_auth" structure is an "auth_flavor" + enumeration followed by up to 400 bytes that are opaque to + (uninterpreted by) the RPC protocol implementation. + + The interpretation and semantics of the data contained within the + authentication fields are specified by individual, independent + authentication protocol specifications. + + If authentication parameters were rejected, the reply message + contains information stating why they were rejected. + + As demonstrated by RPCSEC_GSS, it is possible for an "auth_flavor" to + also support integrity and privacy. + + + + + + + + + + + + + + +Thurlow Standards Track [Page 9] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + +8.3. Program Number Assignment + + Program numbers are given out in groups according to the following + chart: + + 0x00000000 Reserved + 0x00000001 - 0x1fffffff To be assigned by IANA + 0x20000000 - 0x3fffffff Defined by local administrator + (some blocks assigned here) + 0x40000000 - 0x5fffffff Transient + 0x60000000 - 0x7effffff Reserved + 0x7f000000 - 0x7fffffff Assignment outstanding + 0x80000000 - 0xffffffff Reserved + + The first group is a range of numbers administered by IANA and should + be identical for all sites. The second range is for applications + peculiar to a particular site. This range is intended primarily for + debugging new programs. When a site develops an application that + might be of general interest, that application should be given an + assigned number in the first range. Application developers may apply + for blocks of RPC program numbers in the first range by methods + described in Appendix B. The third group is for applications that + generate program numbers dynamically. The final groups are reserved + for future use, and should not be used. + +8.4. Other Uses of the RPC Protocol + + The intended use of this protocol is for calling remote procedures. + Normally, each call message is matched with a reply message. + However, the protocol itself is a message-passing protocol with which + other (non-procedure-call) protocols can be implemented. + +8.4.1. Batching + + Batching is useful when a client wishes to send an arbitrarily large + sequence of call messages to a server. Batching typically uses + reliable byte stream protocols (like TCP) for its transport. In the + case of batching, the client never waits for a reply from the server, + and the server does not send replies to batch calls. A sequence of + batch calls is usually terminated by a legitimate remote procedure + call operation in order to flush the pipeline and get positive + acknowledgement. + + + + + + + + + +Thurlow Standards Track [Page 10] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + +8.4.2. Broadcast Remote Procedure Calls + + In broadcast protocols, the client sends a broadcast call to the + network and waits for numerous replies. This requires the use of + packet-based protocols (like UDP) as its transport protocol. Servers + that support broadcast protocols usually respond only when the call + is successfully processed and are silent in the face of errors, but + this varies with the application. + + The principles of broadcast RPC also apply to multicasting -- an RPC + request can be sent to a multicast address. + +9. The RPC Message Protocol + + This section defines the RPC message protocol in the XDR data + description language [RFC4506]. + + enum msg_type { + CALL = 0, + REPLY = 1 + }; + + A reply to a call message can take on two forms: the message was + either accepted or rejected. + + enum reply_stat { + MSG_ACCEPTED = 0, + MSG_DENIED = 1 + }; + + Given that a call message was accepted, the following is the status + of an attempt to call a remote procedure. + + enum accept_stat { + SUCCESS = 0, /* RPC executed successfully */ + PROG_UNAVAIL = 1, /* remote hasn't exported program */ + PROG_MISMATCH = 2, /* remote can't support version # */ + PROC_UNAVAIL = 3, /* program can't support procedure */ + GARBAGE_ARGS = 4, /* procedure can't decode params */ + SYSTEM_ERR = 5 /* e.g. memory allocation failure */ + }; + + Reasons why a call message was rejected: + + enum reject_stat { + RPC_MISMATCH = 0, /* RPC version number != 2 */ + AUTH_ERROR = 1 /* remote can't authenticate caller */ + }; + + + +Thurlow Standards Track [Page 11] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + Why authentication failed: + + enum auth_stat { + AUTH_OK = 0, /* success */ + /* + * failed at remote end + */ + AUTH_BADCRED = 1, /* bad credential (seal broken) */ + AUTH_REJECTEDCRED = 2, /* client must begin new session */ + AUTH_BADVERF = 3, /* bad verifier (seal broken) */ + AUTH_REJECTEDVERF = 4, /* verifier expired or replayed */ + AUTH_TOOWEAK = 5, /* rejected for security reasons */ + /* + * failed locally + */ + AUTH_INVALIDRESP = 6, /* bogus response verifier */ + AUTH_FAILED = 7, /* reason unknown */ + /* + * AUTH_KERB errors; deprecated. See [RFC2695] + */ + AUTH_KERB_GENERIC = 8, /* kerberos generic error */ + AUTH_TIMEEXPIRE = 9, /* time of credential expired */ + AUTH_TKT_FILE = 10, /* problem with ticket file */ + AUTH_DECODE = 11, /* can't decode authenticator */ + AUTH_NET_ADDR = 12, /* wrong net address in ticket */ + /* + * RPCSEC_GSS GSS related errors + */ + RPCSEC_GSS_CREDPROBLEM = 13, /* no credentials for user */ + RPCSEC_GSS_CTXPROBLEM = 14 /* problem with context */ + }; + + As new authentication mechanisms are added, there may be a need for + more status codes to support them. IANA will hand out new auth_stat + numbers on a simple First Come First Served basis as defined in the + "IANA Considerations" and Appendix B. + + The RPC message: + + All messages start with a transaction identifier, xid, followed by a + two-armed discriminated union. The union's discriminant is a + msg_type that switches to one of the two types of the message. The + xid of a REPLY message always matches that of the initiating CALL + message. NB: The "xid" field is only used for clients matching reply + messages with call messages or for servers detecting retransmissions; + the service side cannot treat this id as any type of sequence number. + + + + + +Thurlow Standards Track [Page 12] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + struct rpc_msg { + unsigned int xid; + union switch (msg_type mtype) { + case CALL: + call_body cbody; + case REPLY: + reply_body rbody; + } body; + }; + + Body of an RPC call: + + In version 2 of the RPC protocol specification, rpcvers MUST be equal + to 2. The fields "prog", "vers", and "proc" specify the remote + program, its version number, and the procedure within the remote + program to be called. After these fields are two authentication + parameters: cred (authentication credential) and verf (authentication + verifier). The two authentication parameters are followed by the + parameters to the remote procedure, which are specified by the + specific program protocol. + + The purpose of the authentication verifier is to validate the + authentication credential. Note that these two items are + historically separate, but are always used together as one logical + entity. + + struct call_body { + unsigned int rpcvers; /* must be equal to two (2) */ + unsigned int prog; + unsigned int vers; + unsigned int proc; + opaque_auth cred; + opaque_auth verf; + /* procedure-specific parameters start here */ + }; + + Body of a reply to an RPC call: + + union reply_body switch (reply_stat stat) { + case MSG_ACCEPTED: + accepted_reply areply; + case MSG_DENIED: + rejected_reply rreply; + } reply; + + + + + + + +Thurlow Standards Track [Page 13] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + Reply to an RPC call that was accepted by the server: + + There could be an error even though the call was accepted. The first + field is an authentication verifier that the server generates in + order to validate itself to the client. It is followed by a union + whose discriminant is an enum accept_stat. The SUCCESS arm of the + union is protocol-specific. The PROG_UNAVAIL, PROC_UNAVAIL, + GARBAGE_ARGS, and SYSTEM_ERR arms of the union are void. The + PROG_MISMATCH arm specifies the lowest and highest version numbers of + the remote program supported by the server. + + struct accepted_reply { + opaque_auth verf; + union switch (accept_stat stat) { + case SUCCESS: + opaque results[0]; + /* + * procedure-specific results start here + */ + case PROG_MISMATCH: + struct { + unsigned int low; + unsigned int high; + } mismatch_info; + default: + /* + * Void. Cases include PROG_UNAVAIL, PROC_UNAVAIL, + * GARBAGE_ARGS, and SYSTEM_ERR. + */ + void; + } reply_data; + }; + + Reply to an RPC call that was rejected by the server: + + The call can be rejected for two reasons: either the server is not + running a compatible version of the RPC protocol (RPC_MISMATCH) or + the server rejects the identity of the caller (AUTH_ERROR). In case + of an RPC version mismatch, the server returns the lowest and highest + supported RPC version numbers. In case of invalid authentication, + failure status is returned. + + + + + + + + + + +Thurlow Standards Track [Page 14] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + union rejected_reply switch (reject_stat stat) { + case RPC_MISMATCH: + struct { + unsigned int low; + unsigned int high; + } mismatch_info; + case AUTH_ERROR: + auth_stat stat; + }; + +10. Authentication Protocols + + As previously stated, authentication parameters are opaque, but + open-ended to the rest of the RPC protocol. This section defines two + standard flavors of authentication. Implementors are free to invent + new authentication types, with the same rules of flavor number + assignment as there are for program number assignment. The flavor of + a credential or verifier refers to the value of the "flavor" field in + the opaque_auth structure. Flavor numbers, like RPC program numbers, + are also administered centrally, and developers may assign new flavor + numbers by methods described in Appendix B. Credentials and + verifiers are represented as variable-length opaque data (the "body" + field in the opaque_auth structure). + + In this document, two flavors of authentication are described. Of + these, Null authentication (described in the next subsection) is + mandatory -- it MUST be available in all implementations. System + authentication (AUTH_SYS) is described in Appendix A. Implementors + MAY include AUTH_SYS in their implementations to support existing + applications. See "Security Considerations" for information about + other, more secure, authentication flavors. + +10.1. Null Authentication + + Often, calls must be made where the client does not care about its + identity or the server does not care who the client is. In this + case, the flavor of the RPC message's credential, verifier, and reply + verifier is "AUTH_NONE". Opaque data associated with "AUTH_NONE" is + undefined. It is recommended that the length of the opaque data be + zero. + + + + + + + + + + + +Thurlow Standards Track [Page 15] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + +11. Record Marking Standard + + When RPC messages are passed on top of a byte stream transport + protocol (like TCP), it is necessary to delimit one message from + another in order to detect and possibly recover from protocol errors. + This is called record marking (RM). One RPC message fits into one RM + record. + + A record is composed of one or more record fragments. A record + fragment is a four-byte header followed by 0 to (2**31) - 1 bytes of + fragment data. The bytes encode an unsigned binary number; as with + XDR integers, the byte order is from highest to lowest. The number + encodes two values -- a boolean that indicates whether the fragment + is the last fragment of the record (bit value 1 implies the fragment + is the last fragment) and a 31-bit unsigned binary value that is the + length in bytes of the fragment's data. The boolean value is the + highest-order bit of the header; the length is the 31 low-order bits. + (Note that this record specification is NOT in XDR standard form!) + +12. The RPC Language + + Just as there was a need to describe the XDR data-types in a formal + language, there is also need to describe the procedures that operate + on these XDR data-types in a formal language as well. The RPC + language is an extension to the XDR language, with the addition of + "program", "procedure", and "version" declarations. The keywords + "program" and "version" are reserved in the RPC language, and + implementations of XDR compilers MAY reserve these keywords even when + provided with pure XDR, non-RPC, descriptions. The following example + is used to describe the essence of the language. + + + + + + + + + + + + + + + + + + + + + +Thurlow Standards Track [Page 16] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + +12.1. An Example Service Described in the RPC Language + + Here is an example of the specification of a simple ping program. + + program PING_PROG { + /* + * Latest and greatest version + */ + version PING_VERS_PINGBACK { + void + PINGPROC_NULL(void) = 0; + /* + * Ping the client, return the round-trip time + * (in microseconds). Returns -1 if the operation + * timed out. + */ + int + PINGPROC_PINGBACK(void) = 1; + } = 2; + + /* + * Original version + */ + version PING_VERS_ORIG { + void + PINGPROC_NULL(void) = 0; + } = 1; + } = 1; + + const PING_VERS = 2; /* latest version */ + + The first version described is PING_VERS_PINGBACK with two + procedures: PINGPROC_NULL and PINGPROC_PINGBACK. PINGPROC_NULL takes + no arguments and returns no results, but it is useful for computing + round-trip times from the client to the server and back again. By + convention, procedure 0 of any RPC protocol should have the same + semantics and never require any kind of authentication. The second + procedure is used for the client to have the server do a reverse ping + operation back to the client, and it returns the amount of time (in + microseconds) that the operation used. The next version, + PING_VERS_ORIG, is the original version of the protocol, and it does + not contain the PINGPROC_PINGBACK procedure. It is useful for + compatibility with old client programs, and as this program matures, + it may be dropped from the protocol entirely. + + + + + + + +Thurlow Standards Track [Page 17] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + +12.2. The RPC Language Specification + + The RPC language is identical to the XDR language defined in RFC + 4506, except for the added definition of a "program-def", described + below. + + program-def: + "program" identifier "{" + version-def + version-def * + "}" "=" constant ";" + + version-def: + "version" identifier "{" + procedure-def + procedure-def * + "}" "=" constant ";" + + procedure-def: + proc-return identifier "(" proc-firstarg + ("," type-specifier )* ")" "=" constant ";" + + proc-return: "void" | type-specifier + + proc-firstarg: "void" | type-specifier + +12.3. Syntax Notes + + o The following keywords are added and cannot be used as + identifiers: "program" and "version". + + o A version name cannot occur more than once within the scope of a + program definition. Neither can a version number occur more than + once within the scope of a program definition. + + o A procedure name cannot occur more than once within the scope of a + version definition. Neither can a procedure number occur more + than once within the scope of version definition. + + o Program identifiers are in the same name space as constant and + type identifiers. + + o Only unsigned constants can be assigned to programs, versions, and + procedures. + + o Current RPC language compilers do not generally support more than + one type-specifier in procedure argument lists; the usual practice + is to wrap arguments into a structure. + + + +Thurlow Standards Track [Page 18] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + +13. IANA Considerations + + The assignment of RPC program numbers, authentication flavor numbers, + and authentication status numbers has in the past been performed by + Sun Microsystems, Inc (Sun). This is inappropriate for an IETF + Standards Track protocol, as such work is done well by the Internet + Assigned Numbers Authority (IANA). This document proposes the + transfer of authority over RPC program numbers, authentication flavor + numbers, and authentication status numbers described here from Sun + Microsystems, Inc. to IANA and describes how IANA will maintain and + assign these numbers. Users of RPC protocols will benefit by having + an independent body responsible for these number assignments. + +13.1. Numbering Requests to IANA + + Appendix B of this document describes the information to be sent to + IANA to request one or more RPC numbers and the rules that apply. + IANA will store the request for documentary purposes and put the + following information into the public registry: + + o The short description of purpose and use + + o The program number(s) assigned + + o The short identifier string(s) + +13.2. Protecting Past Assignments + + Sun has made assignments in both the RPC program number space and the + RPC authentication flavor number space since the original deployment + of RPC. The assignments made by Sun Microsystems are still valid, + and will be preserved. Sun has communicated all current assignments + in both number spaces to IANA and final handoff of number assignment + is complete. Current program and auth number assignments are + provided in Appendix C. Current authentication status numbers are + listed in Section 9 of this document in the "enum auth_stat" + definition. + +13.3. RPC Number Assignment + + Future IANA practice will deal with the following partitioning of the + 32-bit number space as listed in Section 8.3. Detailed information + for the administration of the partitioned blocks in Section 8.3 is + given below. + + + + + + + +Thurlow Standards Track [Page 19] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + +13.3.1. To Be Assigned By IANA + + The first block will be administered by IANA, with previous + assignments by Sun protected. Previous assignments were restricted + to the range decimal 100000-399999 (0x000186a0 to 0x00061a7f); + therefore, IANA will begin assignments at decimal 400000. Individual + numbers should be grated on a First Come First Served basis, and + blocks should be granted under rules related to the size of the + block. + +13.3.2. Defined by Local Administrator + + The "Defined by local administrator" block is available for any local + administrative domain to use, in a similar manner to IP address + ranges reserved for private use. The expected use would be through + the establishment of a local domain "authority" for assigning numbers + from this range. This authority would establish any policies or + procedures to be used within that local domain for use or assignment + of RPC numbers from the range. The local domain should be + sufficiently isolated that it would be unlikely that RPC applications + developed by other local domains could communicate with the domain. + This could result in RPC number contention, which would cause one of + the applications to fail. In the absence of a local administrator, + this block can be utilized in a "Private Use" manner per [RFC5226]. + +13.3.3. Transient Block + + The "Transient" block can be used by any RPC application on an "as + available" basis. This range is intended for services that can + communicate a dynamically selected RPC program number to clients of + the service. Any mechanism can be used to communicate the number. + For example, either shared memory when the client and server are + located on the same system or a network message (either RPC or + otherwise) that disseminates the selected number can be used. + + The transient block is not administered. An RPC service uses this + range by selecting a number in the transient range and attempting to + register that number with the local system's RPC bindery (see the + RPCBPROC_SET or PMAPPROC_SET procedures in "Binding Protocols for ONC + RPC Version 2", [RFC1833]). If successful, no other RPC service was + using that number and the RPC Bindery has assigned that number to the + requesting RPC application. The registration is valid until the RPC + Bindery terminates, which normally would only happen if the system + reboots, causing all applications, including the RPC service using + the transient number, to terminate. If the transient number + registration fails, another RPC application is using the number and + + + + + +Thurlow Standards Track [Page 20] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + the requestor must select another number and try again. To avoid + conflicts, the recommended method is to select a number randomly from + the transient range. + +13.3.4. Reserved Block + + The "Reserved" blocks are available for future use. RPC applications + must not use numbers in these ranges unless their use is allowed by + future action by the IESG. + +13.3.5. RPC Number Sub-Blocks + + RPC numbers are usually assigned for specific RPC services. Some + applications, however, require multiple RPC numbers for a service. + The most common example is an RPC service that needs to have multiple + instances of the service active simultaneously at a specific site. + RPC does not have an "instance identifier" in the protocol, so either + a mechanism must be implemented to multiplex RPC requests amongst + various instances of the service or unique RPC numbers must be used + by each instance. + + In these cases, the RPC protocol used with the various numbers may be + different or the same. The numbers may either be assigned + dynamically by the application, or as part of a site-specific + administrative decision. If possible, RPC services that dynamically + assign RPC numbers should use the "Transient" RPC number block + defined in Section 13.3.3. If not possible, RPC number sub-blocks + may be requested. + + Assignment of RPC Number Sub-Blocks is controlled by the size of the + sub-block being requested. "Specification Required" and "IESG + Approval" are used as defined by Section 4.1 of [RFC5226]. + + Size of sub-block Assignment Method Authority + ----------------- ----------------- --------- + Up to 100 numbers First Come First Served IANA + Up to 1000 numbers Specification Required IANA + More than 1000 numbers IESG Approval required IESG + + Note: sub-blocks can be any size. The limits given above are + maximums, and smaller size sub-blocks are allowed. + + Sub-blocks sized up to 100 numbers may be assigned by IANA on a First + Come First Served basis. The RPC Service Description included in the + range must include an indication of how the sub-block is managed. At + a minimum, the statement should indicate whether the sub-block is + + + + + +Thurlow Standards Track [Page 21] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + used with a single RPC protocol or multiple RPC protocols, and + whether the numbers are dynamically assigned or statically (through + administrative action) assigned. + + Sub-blocks of up to 1000 numbers must be documented in detail. The + documentation must describe the RPC protocol or protocols that are to + be used in the range. It must also describe how the numbers within + the sub-block are to be assigned or used. + + Sub-blocks sized over 1000 numbers must be documented as described + above, and the assignment must be approved by the IESG. It is + expected that this will be rare. + + In order to avoid multiple requests of large blocks of numbers, the + following rule is proposed. + + Requests up to and including 100 RPC numbers are handled via the + First Come First Served assignment method. This 100 number threshold + applies to the total number of RPC numbers assigned to an individual + or entity. For example, if an individual or entity first requests, + say, 70 numbers, and then later requests 40 numbers, then the request + for the 40 numbers will be assigned via the Specification Required + method. As long as the total number of numbers assigned does not + exceed 1000, IANA is free to waive the Specification Required + assignment for incremental requests of less than 100 numbers. + + If an individual or entity has under 1000 numbers and later requests + an additional set of numbers such that the individual or entity would + be granted over 1000 numbers, then the additional request will + require IESG Approval. + +13.4. RPC Authentication Flavor Number Assignment + + The second number space is the authentication mechanism identifier, + or "flavor", number. This number is used to distinguish between + various authentication mechanisms that can be optionally used with an + RPC message. An authentication identifier is used in the "flavor" + field of the "opaque_auth" structure. + +13.4.1. Assignment Policy + + Appendix B of this document describes the information to be sent to + IANA to request one or more RPC auth numbers and the rules that + apply. IANA will store the request for documentary purposes and put + the following information into the public registry: + + + + + + +Thurlow Standards Track [Page 22] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + o The short identifier string(s) + + o The auth number(s) assigned + + o The short description of purpose and use + +13.4.2. Auth Flavors vs. Pseudo-Flavors + + Recent progress in RPC security has moved away from new auth flavors + as used by AUTH_DH [DH], and has focused on using the existing + RPCSEC_GSS [RFC2203] flavor and inventing novel GSS-API (Generic + Security Services Application Programming Interface) mechanisms that + can be used with it. Even though RPCSEC_GSS is an assigned + authentication flavor, use of a new RPCSEC_GSS mechanism with the + Network File System (NFS) ([RFC1094] [RFC1813], and [RFC3530]) will + require the registration of 'pseudo-flavors' that are used to + negotiate security mechanisms in an unambiguous way, as defined by + [RFC2623]. Existing pseudo-flavors have been granted in the decimal + range 390000-390255. New pseudo-flavor requests will be granted by + IANA within this block on a First Come First Served basis. + + For non-pseudo-flavor requests, IANA will begin granting RPC + authentication flavor numbers at 400000 on a First Come First Served + basis to avoid conflicts with currently granted numbers. + + For authentication flavors or RPCSEC_GSS mechanisms to be used on the + Internet, it is strongly advised that an Informational or Standards + Track RFC be published describing the authentication mechanism + behaviour and parameters. + +13.5. Authentication Status Number Assignment + + The final number space is the authentication status or "auth_stat" + values that describe the nature of a problem found during an attempt + to authenticate or validate authentication. The complete initial + list of these values is found in Section 9 of this document, in the + "auth_stat" enum listing. It is expected that it will be rare to add + values, but that a small number of new values may be added from time + to time as new authentication flavors introduce new possibilities. + Numbers should be granted on a First Come First Served basis to avoid + conflicts with currently granted numbers. + +13.5.1. Assignment Policy + + Appendix B of this document describes the information to be sent to + IANA to request one or more auth_stat values and the rules that + apply. IANA will store the request for documentary purposes, and put + the following information into the public registry: + + + +Thurlow Standards Track [Page 23] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + o The short identifier string(s) + + o The auth_stat number(s) assigned + + o The short description of purpose and use + +14. Security Considerations + + AUTH_SYS as described in Appendix A is known to be insecure due to + the lack of a verifier to permit the credential to be validated. + AUTH_SYS SHOULD NOT be used for services that permit clients to + modify data. AUTH_SYS MUST NOT be specified as RECOMMENDED or + REQUIRED for any Standards Track RPC service. + + AUTH_DH as mentioned in Sections 8.2 and 13.4.2 is considered + obsolete and insecure; see [RFC2695]. AUTH_DH SHOULD NOT be used for + services that permit clients to modify data. AUTH_DH MUST NOT be + specified as RECOMMENDED or REQUIRED for any Standards Track RPC + service. + + [RFC2203] defines a new security flavor, RPCSEC_GSS, which permits + GSS-API [RFC2743] mechanisms to be used for securing RPC. All non- + trivial RPC programs developed in the future should implement + RPCSEC_GSS-based security appropriately. [RFC2623] describes how + this was done for a widely deployed RPC program. + + Standards Track RPC services MUST mandate support for RPCSEC_GSS, and + MUST mandate support for an authentication pseudo-flavor with + appropriate levels of security, depending on the need for simple + authentication, integrity (a.k.a. non-repudiation), or data privacy. + + + + + + + + + + + + + + + + + + + + + +Thurlow Standards Track [Page 24] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + +Appendix A: System Authentication + + The client may wish to identify itself, for example, as it is + identified on a UNIX(tm) system. The flavor of the client credential + is "AUTH_SYS". The opaque data constituting the credential encodes + the following structure: + + struct authsys_parms { + unsigned int stamp; + string machinename<255>; + unsigned int uid; + unsigned int gid; + unsigned int gids<16>; + }; + + The "stamp" is an arbitrary ID that the caller machine may generate. + The "machinename" is the name of the caller's machine (like + "krypton"). The "uid" is the caller's effective user ID. The "gid" + is the caller's effective group ID. "gids" are a counted array of + groups that contain the caller as a member. The verifier + accompanying the credential should have "AUTH_NONE" flavor value + (defined above). Note that this credential is only unique within a + particular domain of machine names, uids, and gids. + + The flavor value of the verifier received in the reply message from + the server may be "AUTH_NONE" or "AUTH_SHORT". In the case of + "AUTH_SHORT", the bytes of the reply verifier's string encode an + opaque structure. This new opaque structure may now be passed to the + server instead of the original "AUTH_SYS" flavor credential. The + server may keep a cache that maps shorthand opaque structures (passed + back by way of an "AUTH_SHORT" style reply verifier) to the original + credentials of the caller. The caller can save network bandwidth and + server cpu cycles by using the shorthand credential. + + The server may flush the shorthand opaque structure at any time. If + this happens, the remote procedure call message will be rejected due + to an authentication error. The reason for the failure will be + "AUTH_REJECTEDCRED". At this point, the client may wish to try the + original "AUTH_SYS" style of credential. + + It should be noted that use of this flavor of authentication does not + guarantee any security for the users or providers of a service, in + itself. The authentication provided by this scheme can be considered + legitimate only when applications using this scheme and the network + can be secured externally, and privileged transport addresses are + used for the communicating end-points (an example of this is the use + of privileged TCP/UDP ports in UNIX systems -- note that not all + systems enforce privileged transport address mechanisms). + + + +Thurlow Standards Track [Page 25] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + +Appendix B: Requesting RPC-Related Numbers from IANA + + RPC program numbers, authentication flavor numbers, and + authentication status numbers that must be unique across all networks + are assigned by the Internet Assigned Number Authority. To apply for + a single number or a block of numbers, electronic mail must be sent + to IANA with the following information: + + o The type of number(s) (program number or authentication flavor + number or authentication status number) sought + + o How many numbers are sought + + o The name of the person or company that will use the number + + o An "identifier string" that associates the number with a service + + o Email address of the contact person for the service that will be + using the number + + o A short description of the purpose and use of the number + + o If an authentication flavor number is sought, and the number will + be a 'pseudo-flavor' intended for use with RPCSEC_GSS and NFS, + mappings analogous to those in Section 4.2 of [RFC2623] + + Specific numbers cannot be requested. Numbers are assigned on a + First Come First Served basis. + + For all RPC authentication flavor and authentication status numbers + to be used on the Internet, it is strongly advised that an + Informational or Standards Track RFC be published describing the + authentication mechanism behaviour and parameters. + + + + + + + + + + + + + + + + + + +Thurlow Standards Track [Page 26] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + +Appendix C: Current Number Assignments + + # + # Sun-assigned RPC numbers + # + # Description/Owner RPC Program Number Short Name + # ----------------------------------------------------------------- + portmapper 100000 pmapprog portmap rpcbind + remote stats 100001 rstatprog + remote users 100002 rusersprog + nfs 100003 nfs + yellow pages (NIS) 100004 ypprog ypserv + mount demon 100005 mountprog + remote dbx 100006 dbxprog + yp binder (NIS) 100007 ypbindprog ypbind + shutdown msg 100008 wall + yppasswd server 100009 yppasswdprog yppasswdd + ether stats 100010 etherstatprog + disk quotas 100011 rquota + spray packets 100012 spray + 3270 mapper 100013 ibm3270prog + RJE mapper 100014 ibmrjeprog + selection service 100015 selnsvcprog + remote database access 100016 rdatabaseprog + remote execution 100017 rexec + Alice Office Automation 100018 aliceprog + scheduling service 100019 schedprog + local lock manager 100020 lockprog llockmgr + network lock manager 100021 netlockprog nlockmgr + x.25 inr protocol 100022 x25prog + status monitor 1 100023 statmon1 + status monitor 2 100024 statmon2 + selection library 100025 selnlibprog + boot parameters service 100026 bootparam + mazewars game 100027 mazeprog + yp update (NIS) 100028 ypupdateprog ypupdate + key server 100029 keyserveprog + secure login 100030 securecmdprog + nfs net forwarder init 100031 netfwdiprog + nfs net forwarder trans 100032 netfwdtprog + sunlink MAP 100033 sunlinkmap + network monitor 100034 netmonprog + lightweight database 100035 dbaseprog + password authorization 100036 pwdauthprog + translucent file svc 100037 tfsprog + nse server 100038 nseprog + nse activate daemon 100039 nse_activate_prog + sunview help 100040 sunview_help_prog + + + +Thurlow Standards Track [Page 27] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + pnp install 100041 pnp_prog + ip addr allocator 100042 ipaddr_alloc_prog + show filehandle 100043 filehandle + MVS NFS mount 100044 mvsnfsprog + remote user file operations 100045 rem_fileop_user_prog + batched ypupdate 100046 batch_ypupdateprog + network execution mgr 100047 nem_prog + raytrace/mandelbrot remote daemon 100048 raytrace_rd_prog + raytrace/mandelbrot local daemon 100049 raytrace_ld_prog + remote group file operations 100050 rem_fileop_group_prog + remote system file operations 100051 rem_fileop_system_prog + remote system role operations 100052 rem_system_role_prog + gpd lego fb simulator 100053 [unknown] + gpd simulator interface 100054 [unknown] + ioadmd 100055 ioadmd + filemerge 100056 filemerge_prog + Name Binding Program 100057 namebind_prog + sunlink NJE 100058 njeprog + MVSNFS get attribute service 100059 mvsattrprog + SunAccess/SunLink resource manager 100060 rmgrprog + UID allocation service 100061 uidallocprog + license broker 100062 lbserverprog + NETlicense client binder 100063 lbbinderprog + GID allocation service 100064 gidallocprog + SunIsam 100065 sunisamprog + Remote Debug Server 100066 rdbsrvprog + Network Directory Daemon 100067 [unknown] + Network Calendar Program 100068 cmsd cm + ypxfrd 100069 ypxfrd + rpc.timed 100070 timedprog + bugtraqd 100071 bugtraqd + 100072 [unknown] + Connectathon Billboard - NFS 100073 [unknown] + Connectathon Billboard - X 100074 [unknown] + Sun tool for scheduling rooms 100075 schedroom + Authentication Negotiation 100076 authnegotiate_prog + Database manipulation 100077 attribute_prog + Kerberos authentication daemon 100078 kerbprog + Internal testing product (no name) 100079 [unknown] + Sun Consulting Special 100080 autodump_prog + Event protocol 100081 event_svc + bugtraq_qd 100082 bugtraq_qd + ToolTalk and Link Service Project 100083 database service + Consulting Services 100084 [unknown] + Consulting Services 100085 [unknown] + Consulting Services 100086 [unknown] + Jupiter Administration 100087 adm_agent admind + 100088 [unknown] + + + +Thurlow Standards Track [Page 28] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + 100089 [unknown] + Dual Disk support 100090 libdsd/dsd + DocViewer 1.1 100091 [unknown] + ToolTalk 100092 remote_activation_svc + Consulting Services 100093 host_checking + SNA peer-to-peer 100094 [unknown] + Roger Riggs 100095 searchit + Robert Allen 100096 mesgtool + SNA 100097 [unknown] + SISU 100098 networked version of CS5 + NFS Automount File System 100099 autofs + 100100 msgboard + event dispatching agent [eventd] 100101 netmgt_eventd_prog + statistics/event logger [netlogd] 100102 netmgt_netlogd_prog + topology display manager [topology]100103 netmgt_topology_prog + syncstat agent [syncstatd] 100104 netmgt_syncstatd_prog + ip packet stats agent [ippktd] 100105 netmgt_ippktd_prog + netmgt config agent [configd] 100106 netmgt_configd_prog + restat agent [restatd] 100107 netmgt_restatd_prog + lpq agent [lprstatd] 100108 netmgt_lprstatd_prog + netmgt activity agent [mgtlogd] 100109 netmgt_mgtlogd_prog + proxy DECnet NCP agent [proxydni] 100110 netmgt_proxydni_prog + topology mapper agent [mapperd] 100111 netmgt_mapperd_prog + netstat agent [netstatd] 100112 netmgt_netstatd_prog + sample netmgt agent [sampled] 100113 netmgt_sampled_prog + X.25 statistics agent [vcstatd] 100114 netmgt_vcstatd_prog + Frame Relay 100128 [unknown] + PPP agent 100129 [unknown] + localhad 100130 rpc.localhad + layers2 100131 na.layers2 + token ring agent 100132 na.tr + related to lockd and statd 100133 nsm_addr + Kerberos project 100134 kwarn + ertherif2 100135 na.etherif2 + hostmem2 100136 na.hostmem2 + iostat2 100137 na.iostat2 + snmpv2 100138 na.snmpv2 + Cooperative Console 100139 cc_sender + na.cpustat 100140 na.cpustat + Sun Cluster SC3.0 100141 rgmd_receptionist + 100142 fed + Network Storage 100143 rdc + Sun Cluster products 100144 nafo + SunCluster 3.0 100145 scadmd + ASN.1 100146 amiserv + 100147 amiaux # BER and DER + encode and decode + Delegate Management Server 100148 dm + + + +Thurlow Standards Track [Page 29] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + 100149 rkstat + 100150 ocfserv + 100151 sccheckd + 100152 autoclientd + 100153 sunvts + 100154 ssmond + 100155 smserverd + 100156 test1 + 100157 test2 + 100158 test3 + 100159 test4 + 100160 test5 + 100161 test6 + 100162 test7 + 100163 test8 + 100164 test9 + 100165 test10 + 100166 nfsmapid + 100167 SUN_WBEM_C_CIMON_HANDLE + 100168 sacmmd + 100169 fmd_adm + 100170 fmd_api + 100171 [unknown] + 100172 idmapd + unassigned 100173 - 100174 + snmptrap 100175 na.snmptrap + unassigned 100176-100199 + + unassigned 100200 + MVS/NFS Memory usage stats server 100201 [unknown] + Netapp 100202-100207 + unassigned 100208-100210 + 8.0 SunLink SNA RJE 100211 [unknown] + 8.0 SunLink SNA RJE 100212 [unknown] + 100213 ShowMe + 100214 [unknown] + 100215 [unknown] + AUTH_RSA Key service 100216 keyrsa + SunSelect PC license service 100217 [unknown] + WWCS (Corporate) 100218 sunsolve + 100219 cstatd + X/Open Federated Naming 100220 xfn_server_prog + Kodak Color Management System 100221 kcs_network_io kcs + HA-DBMS 100222 ha_dbms_serv + 100223-100225 [unknown] + 100226 hafaultd + NFS ACL Service 100227 nfs_acl + distributed lock manager 100228 dlmd + + + +Thurlow Standards Track [Page 30] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + 100229 metad + 100230 metamhd + 100231 nfsauth + 100232 sadmind + 100233 ufsd + 100234 grpservd + 100235 cachefsd + 100236 msmprog Media_Server + 100237 ihnamed + 100238 ihnetd + 100239 ihsecured + 100240 ihclassmgrd + 100241 ihrepositoryd + 100242 metamedd rpc.metamedd + 100243 contentmanager cm + 100244 symon + 100245 pld genesil + 100246 ctid + cluster_transport_interface + 100247 ccd + cluster_configuration_db + 100248 pmfd + 100249 dmi2_client + 100250 mfs_admin + 100251 ndshared_unlink + 100252 ndshared_touch + 100253 ndshared_slink + 100254 cbs control_board_server + 100255 skiserv + 100256 nfsxa nfsxattr + 100257 ndshared_disable + 100258 ndshared_enable + 100259 sms_account_admin + 100260 sms_modem_admin + 100261 sms_r_login + 100262 sms_r_subaccount_mgt + 100263 sms_service_admin + 100264 session_admin + 100265 canci_ancs_program + 100266 canci_sms_program + 100267 msmp + 100268 halck + 100269 halogmsg + 100270 nfs_id_map + 100271 ncall + 100272 hmip + 100273 repl_mig + 100274 repl_mig_cb + + + +Thurlow Standards Track [Page 31] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + NIS+ 100300 nisplus + NIS+ 100301 nis_cachemgr + NIS+ call back protocol 100302 [unknown] + NIS+ Password Update Daemon 100303 nispasswdd + FNS context update in NIS 100304 fnsypd + 100305 [unknown] + 100306 [unknown] + 100307 [unknown] + 100308 [unknown] + 100309 [unknown] + unassigned 100310 - 100398 + nfscksum 100399 nfscksum + network utilization agent 100400 netmgt_netu_prog + network rpc ping agent 100401 netmgt_rping_prog + 100402 na.shell + picsprint 100403 na.picslp + 100404 traps + 100405 - 100409 [unknown] + 100410 jdsagent + 100411 na.haconfig + 100412 na.halhost + 100413 na.hadtsrvc + 100414 na.hamdstat + 100415 na.neoadmin + 100416 ex1048prog + rdmaconfig 100417 rpc.rdmaconfig + IETF NFSv4 Working Group - FedFS 100418 - 100421 + 100422 mdcommd + 100423 kiprop krb5_iprop + 100424 stsf + unassigned 100425 - 100499 + Sun Microsystems 100500 - 100531 [unknown] + 100532 ucmmstate + 100533 scrcmd + unassigned 100534 - 100999 + nse link daemon 101002 nselinktool + nse link application 101003 nselinkapp + unassigned 101004 - 101900 + 101901 [unknown] + unassigned 101902 - 101999 + AssetLite 102000 [unknown] + PagerTool 102001 [unknown] + Discover 102002 [unknown] + unassigned 102003 - 105000 + ShowMe 105001 sharedapp + Registry 105002 REGISTRY_PROG + Print-server 105003 print-server + Proto-server 105004 proto-server + + + +Thurlow Standards Track [Page 32] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + Notification-server 105005 notification-server + Transfer-agent-server 105006 transfer-agent-server + unassigned 105007 - 110000 + 110001 tsolrpcb + 110002 tsolpeerinfo + 110003 tsolboot + 120001 cmip na.cmip + 120002 na.osidiscover + 120003 cmiptrap + unassigned 120004 - 120099 + 120100 eserver + 120101 repserver + 120102 swserver + 120103 dmd + 120104 ca + unassigned 120105 - 120125 + 120126 nf_fddi + 120127 nf_fddismt7_2 + unassigned 120128 - 150000 + pc passwd authorization 150001 pcnfsdprog + TOPS name mapping 150002 [unknown] + TOPS external attribute storage 150003 [unknown] + TOPS hierarchical file system 150004 [unknown] + TOPS NFS transparency extensions 150005 [unknown] + PC NFS License 150006 pcnfslicense + RDA 150007 rdaprog + WabiServer 150008 wsprog + WabiServer 150009 wsrlprog + unassigned 150010 - 160000 + 160001 nihon-cm + 160002 nihon-ce + unassigned 160003 - 170099 + 170100 domf_daemon0 + 170101 domf_daemon1 + 170102 domf_daemon2 + 170103 domf_daemon3 + 170104 domf_daemon4 + 170105 domf_daemon5 + unassigned 170106 - 179999 + 180000 cecprog + 180001 cecsysprog + 180002 cec2cecprog + 180003 cesprog + 180004 ces2cesprog + 180005 cet2cetprog + 180006 cet2cetdoneprog + 180007 cetcomprog + 180008 cetsysprog + + + +Thurlow Standards Track [Page 33] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + 180009 cghapresenceprog + 180010 cgdmsyncprog + 180011 cgdmcnscliprog + 180012 cgdmcrcscliprog + 180013 cgdmcrcssvcproG + 180014 chmprog + 180015 chmsysprog + 180016 crcsapiprog + 180017 ckptmprog + 180018 crimcomponentprog + 180019 crimqueryprog + 180020 crimsecondaryprog + 180021 crimservicesprog + 180022 crimsyscomponentprog + 180023 crimsysservicesprog + 180024 csmagtapiprog + 180025 csmagtcallbackprog + 180026 csmreplicaprog + 180027 csmsrvprog + 180028 cssccltprog + 180029 csscsvrprog + 180030 csscopresultprog + unassigned 180031 - 199999 + 200000 pyramid_nfs + 200001 pyramid_reserved + 200002 cadds_image + 200003 stellar_name_prog + 200004 [unknown] + 200005 [unknown] + 200006 pacl + 200007 lookupids + 200008 ax_statd_prog + 200009 ax_statd2_prog + 200010 edm + 200011 dtedirwd + 200012 [unknown] + 200013 [unknown] + 200014 [unknown] + 200015 [unknown] + 200016 easerpcd + 200017 rlxnfs + 200018 sascuiddprog + 200019 knfsd + 200020 ftnfsd ftnfsd_program + 200021 ftsyncd ftsyncd_program + 200022 ftstatd ftstatd_program + 200023 exportmap + 200024 nfs_metadata + + + +Thurlow Standards Track [Page 34] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + unassigned 200025 - 200200 + 200201 ecoad + 200202 eamon + 200203 ecolic + 200204 cs_printstatus_svr + 200205 ecodisc + unassigned 200206 - 300000 + 300001 adt_rflockprog + 300002 columbine1 + 300003 system33_prog + 300004 frame_prog1 + 300005 uimxprog + 300006 rvd + 300007 entombing daemon + 300008 account mgmt system + 300009 frame_prog2 + 300010 beeper access + 300011 dptuprog + 300012 mx-bcp + 300013 instrument-file-access + 300014 file-system-statistics + 300015 unify-database-server + 300016 tmd_msg + 300017 [unknown] + 300018 [unknown] + 300019 automounter access + 300020 lock server + 300021 [unknown] + 300022 office-automation-1 + 300023 office-automation-2 + 300024 office-automation-3 + 300025 office-automation-4 + 300026 office-automation-5 + 300027 office-automation-6 + 300028 office-automation-7 + 300029 local-data-manager + 300030 chide + 300031 csi_program + 300032 [unknown] + 300033 online-help + 300034 case-tool + 300035 delta + 300036 rgi + 300037 instrument-config-server + 300038 [unknown] + 300039 [unknown] + 300040 dtia-rpc-server + 300041 cms + + + +Thurlow Standards Track [Page 35] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + 300042 viewer + 300043 aqm + 300044 exclaim + 300045 masterplan + 300046 fig_tool + 300047 [unknown] + 300048 [unknown] + 300049 [unknown] + 300050 remote-lock-manager + 300051 [unknown] + 300052 gdebug + 300053 ldebug + 300054 rscanner + 300055 [unknown] + 300056 [unknown] + 300057 [unknown] + 300058 [unknown] + 300059 [unknown] + 300060 [unknown] + 300061 [unknown] + 300062 [unknown] + 300063 [unknown] + 300064 [unknown] + 300065 [unknown] + 300066 nSERVER + 300067 [unknown] + 300068 [unknown] + 300069 [unknown] + 300070 [unknown] + 300071 BioStation + 300072 [unknown] + 300073 NetProb + 300074 Logging + 300075 Logging + 300076 [unknown] + 300077 [unknown] + 300078 [unknown] + 300079 [unknown] + 300080 [unknown] + 300081 [unknown] + 300082 sw_twin + 300083 remote_get_login + 300084 odcprog + 300085 [unknown] + 300086 [unknown] + 300087 [unknown] + 300088 [unknown] + 300089 [unknown] + + + +Thurlow Standards Track [Page 36] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + 300090 [unknown] + 300091 smartdoc + 300092 superping + 300093 distributed-chembench + 300094 uacman/alfil-uacman + 300095 ait_rcagent_prog + 300096 ait_rcagent_appl_prog + 300097 smart + 300098 ecoprog + 300099 leonardo + 300100 [unknown] + 300101 [unknown] + 300102 [unknown] + 300103 [unknown] + 300104 [unknown] + 300105 [unknown] + 300106 [unknown] + 300107 [unknown] + 300108 wingz + 300109 teidan + 300110 [unknown] + 300111 [unknown] + 300112 [unknown] + 300113 [unknown] + 300114 [unknown] + 300115 [unknown] + 300116 cadc_fhlockprog + 300117 highscan + 300118 [unknown] + 300119 [unknown] + 300120 [unknown] + 300121 opennavigator + 300122 aarpcxfer + 300123 [unknown] + 300124 [unknown] + 300125 [unknown] + 300126 groggs + 300127 licsrv + 300128 issdemon + 300129 [unknown] + 300130 maximize + 300131 cgm_server + 300132 [unknown] + 300133 agent_rpc + 300134 docmaker + 300135 docmaker + 300136 [unknown] + 300137 [unknown] + + + +Thurlow Standards Track [Page 37] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + 300138 [unknown] + 300139 iesx + 300140 [unknown] + 300141 [unknown] + 300142 [unknown] + 300143 [unknown] + 300144 smart-mbs + 300145 [unknown] + 300146 [unknown] + 300147 docimage + 300148 [unknown] + 300149 dmc-interface + 300150 [unknown] + 300151 jss + 300152 [unknown] + 300153 arimage + 300154 xdb-workbench + 300155 frontdesk + 300156 dmc + 300157 expressight-6000 + 300158 graph service program + 300159 [unknown] + 300160 [unknown] + 300161 [unknown] + 300162 [unknown] + 300163 [unknown] + 300164 [unknown] + 300165 [unknown] + 300166 [unknown] + 300167 [unknown] + 300168 [unknown] + 300169 [unknown] + 300170 [unknown] + 300171 [unknown] + 300172 [unknown] + 300173 [unknown] + 300174 [unknown] + 300175 [unknown] + 300176 rlpr + 300177 nx_hostdprog + 300178 netuser-x + 300179 rmntprog + 300180 [unknown] + 300181 mipe + 300182 [unknown] + 300183 collectorprog + 300184 uslookup_PROG + 300185 viewstation + + + +Thurlow Standards Track [Page 38] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + 300186 iate + 300187 [unknown] + 300188 [unknown] + 300189 [unknown] + 300190 imsvtprog + 300191 [unknown] + 300192 [unknown] + 300193 [unknown] + 300194 pmdb + 300195 pmda + 300196 [unknown] + 300197 [unknown] + 300198 trend_idbd + 300199 rres + 300200 sd.masterd + 300201 sd.executiond + 300202 sd.listend + 300203 sd.reserve1 + 300204 sd.reserve2 + 300205 msbd + 300206 stagedprog + 300207 mountprog + 300208 watchdprog + 300209 pms + 300210 [unknown] + 300211 session_server_program + 300212 session_program + 300213 debug_serverprog + 300214 [unknown] + 300215 [unknown] + 300216 paceprog + 300217 [unknown] + 300218 mbus + 300219 aframes2ps + 300220 npartprog + 300221 cm1server + 300222 cm1bridge + 300223 sailfrogfaxprog + 300224 sailfrogphoneprog + 300225 sailfrogvmailprog + 300226 wserviceprog arcstorm + 300227 hld + 300228 alive + 300229 radsp + 300230 radavx + 300231 radview + 300232 rsys_prog + 300233 rsys_prog + + + +Thurlow Standards Track [Page 39] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + 300234 fm_rpc_prog + 300235 aries + 300236 uapman + 300237 ddman + 300238 top + 300239 [unknown] + 300240 trendlink + 300241 licenseprog + 300242 statuslicenseprog + 300243 oema_rmpf_svc + 300244 oema_smpf_svc + 300245 oema_rmsg_svc + 300246 grapes-sd + 300247 ds_master + 300248 ds_transfer + 300249 ds_logger + 300250 ds_query + 300251 [unknown] + 300252 [unknown] + 300253 nsd_prog + 300254 browser + 300255 epoch + 300256 floorplanner + 300257 reach + 300258 tactic + 300259 cachescientific1 + 300260 cachescientific2 + 300261 desksrc_prog + 300262 photo3d1 + 300263 photo3d2 + 300264 [unknown] + 300265 soundmgr + 300266 s6k + 300267 aims_referenced_ + text_processor + 300268 xess + 300269 ds_queue + 300270 [unknown] + 300271 orionscanplus + 300272 openlink-xx + 300273 kbmsprog + 300274 [unknown] + 300275 futuresource + 300276 the_xprt + 300277 cmg_srvprog + 300278 [unknown] + 300279 [unknown] + 300280 front + + + +Thurlow Standards Track [Page 40] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + 300281 [unknown] + 300282 [unknown] + 300283 [unknown] + 300284 conmanprog + 300285 jincv2 + 300286 isls + 300287 systemstatprog + 300288 fxpsprog + 300289 callpath + 300290 axess + 300291 armor_rpcd + 300292 armor_dictionary_rpcd + 300293 armor_miscd + 300294 filetransfer_prog + 300295 bl_swda + 300296 bl_hwda + 300297 [unknown] + 300298 [unknown] + 300299 [unknown] + 300300 filemon + 300301 acunetprog + 300302 rbuild + 300303 assistprog + 300304 tog + 300305 [unknown] + 300306 sns7000 + 300307 igprog + 300308 tgprog + 300309 plc + 300310 pxman pxlsprog + 300311 hde_server hdeserver + 300312 tsslicenseprog + 300313 rpc.explorerd + 300314 chrd + 300315 tbisam + 300316 tbis + 300317 adsprog + 300318 sponsorprog + 300319 querycmprog + 300320 [unknown] + 300321 [unknown] + 300322 mobil1 + 300323 sld + service_locator_daemon + 300324 linkprog + 300325 codexdaemonprog + 300326 drprog + 300327 ressys_commands + + + +Thurlow Standards Track [Page 41] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + 300328 stamp + 300329 matlab + 300330 sched1d + 300331 upcprog + 300332 xferbkch + 300333 xfer + 300334 qbthd + 300335 qbabort + 300336 lsd + 300337 geomgrd + 300338 generic_fts + 300339 ft_ack + 300340 lymb + 300341 vantage + 300342 cltstd clooptstdprog + 300343 clui clui_prog + 300344 testerd tstdprog + 300345 extsim + 300346 cmd_dispatch maxm_ems + 300347 callpath_receive_program + 300348 x3270prog + 300349 sbc_lag + 300350 sbc_frsa + 300351 sbc_frs + 300352 atommgr + 300353 geostrat + 300354 dbvialu6.2 + 300355 [unknown] + 300356 fxncprog + 300357 infopolic + 300358 [unknown] + 300359 aagns + 300360 aagms + 300361 [unknown] + 300362 clariion_mgr + 300363 setcimrpc + 300364 virtual_protocol_adapter + 300365 unibart + 300366 uniarch + 300367 unifile + 300368 unisrex + 300369 uniscmd + 300370 rsc + 300371 set + 300372 desaf-ws/key + 300373 reeldb + 300374 nl + 300375 rmd + + + +Thurlow Standards Track [Page 42] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + 300376 agcd + 300377 rsynd + 300378 rcnlib + 300379 rcnlib_attach + 300380 evergreen_mgmt_agent + 300381 fx104prog + 300382 rui + remote_user_interface + 300383 ovomd + 300384 [unknown] + 300385 [unknown] + 300386 system_server + 300387 pipecs cs_pipeprog + ppktrpc + 300388 uv-net univision + 300389 auexe + 300390 audip + 300391 mqi + 300392 eva + 300393 eeei_reserved_1 + 300394 eeei_reserved_2 + 300395 eeei_reserved_3 + 300396 eeei_reserved_4 + 300397 eeei_reserved_5 + 300398 eeei_reserved_6 + 300399 eeei_reserved_7 + 300400 eeei_reserved_8 + 300401 cprlm + 300402 wg_idms_manager + 300403 timequota + 300404 spiff + 300405-300414 ov_oem_svc + 300415 ov_msg_ctlg_svc + 300416 ov_advt_reg_svc + 300417-300424 showkron + 300425 daatd + 300426 swiftnet + 300427 ovomdel + 300428 ovomreq + 300429 msg_dispatcher + 300430 pcshare server + 300431 rcvs + 300432 fdfserver + 300433 bssd + 300434 drdd + 300435 mif_gutsprog + 300436 mif_guiprog + 300437 twolfd + + + +Thurlow Standards Track [Page 43] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + 300438 twscd + 300439 nwsbumv + 300440 dgux_mgr + 300441 pfxd + 300442 tds + 300443 ovomadmind + 300444 ovomgate + 300445 omadmind + 300446 nps + 300447 npd + 300448 tsa + 300449 cdaimc + unassigned 300450-300452 + 300453 ckt_implementation + 300454 mda-tactical + unassigned 300455-300458 + 300459 atrrun + 300460 RoadRunner + 300461 nas + 300462 undelete + 300463 ovacadd + 300464 tbdesmai + 300465 arguslm + 300466 dmd + 300467 drd + 300468 fm_help + 300469 ftransrpc_prog + 300470 finrisk + 300471 dg_pc_idisched + 300472 dg_pc_idiserv + 300473 apd + 300474 ap_sspd + 300475 callpatheventrecorder + 300476 flc + 300477 dg_osm + 300478 dspnamed + 300479 iqddsrv + 300480 iqjobsrv + 300481 tacosxx + 300482 wheeldbmg + 300483 cnxmgr_nm_prog + 300484 cnxmgr_cfg_prog + 300485 3dsmapper + 300486 ids + 300487 imagine_rpc_svc + 300488 lfn + 300489 salesnet + 300490 defaxo + + + +Thurlow Standards Track [Page 44] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + 300491 dbqtsd + 300492 kms + 300493 rpc.iced + 300494 calc2s + 300495 ptouidprog + 300496 docsls + 300497 new + 300498 collagebdg + 300499 ars_server + 300500 ars_client + 300501 vr_catalog + 300502 vr_tdb + 300503 ama + 300504 evama + 300505 conama + 300506 service_process + 300507 reuse_proxy + 300508 mars_ctrl + 300509 mars_db + 300510 mars_com + 300511 mars_admch + 300512 tbpipcip + 300513 top_acs_svc + 300514 inout_svc + 300515 csoft_wp + 300516 mcfs + 300517 eventprog + 300518 dg_pc_idimsg + 300519 dg_pc_idiaux + 300520 atsr_gc + 300521 alarm alarm_prog + 300522 fts_prog + 300523 dcs_prog + 300524 ihb_prog + 300525 [unknown] + 300526 [unknown] + 300527 clu_info_prog + 300528 rmfm + 300529 c2sdocd + 300530 interahelp + 300531 callpathasyncmsghandler + 300532 optix_arc + 300533 optix_ts + 300534 optix_wf + 300535 maxopenc + 300536 cev cev_server + 300537 sitewideprog + 300538 drs + + + +Thurlow Standards Track [Page 45] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + 300539 drsdm + 300540 dasgate + 300541 dcdbd + 300542 dcpsd + 300543 supportlink_prog + 300544 broker + 300545 listner + 300546 multiaccess + 300547 spai_interface + 300548 spai_adaption + 300549 chimera_ci + chimera_clientinterface + 300550 chimera_pi + chimera_processinvoker + 300551 teamware_fl + teamware_foundationlevel + 300552 teamware_sl + teamware_systemlevel + 300553 teamware_ui + teamware_userinterface + 300554 lprm + 300555 mpsprog + Mensuration_Proxy_Server + 300556 mo_symdis + 300557 retsideprog + 300558 slp + 300559 slm-api + 300560 im_rpc teamconference + 300561 license_prog license + 300562 stuple stuple_prog + 300563 upasswd_prog + 300564 gentranmentorsecurity + 300565 gentranmentorprovider + 300566 latituded + latitude_license_server + 300567 gentranmentorreq1 + 300568 gentranmentorreq2 + 300569 gentranmentorreq3 + 300570 rj_server + 300571 gws-rdb + 300572 gws-mpmd + 300573 gws-spmd + 300574 vwcalcd + 300575 vworad + 300576 vwsybd + 300577 vwave + 300578 online_assistant + 300579 internet_assistant + + + +Thurlow Standards Track [Page 46] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + 300580 spawnd + 300581 procmgrg + 300582 cfgdbd + 300583 logutild + 300584 ibis + 300585 ibisaux + 300586 aapi + 300587 rstrt + 300588 hbeat + 300589 pcspu + 300590 empress + 300591 sched_server + LiveScheduler + 300592 path_server + LiveScheduler + 300593 c2sdmd + 300594 c2scf + 300595 btsas + 300596 sdtas + 300597 appie + 300598 dmi + 300599 pscd + panther software corp daemon + 300600 sisd + 300601 cpwebserver + 300602 wwcommo + 300603 mx-mie + 300604 mx-mie-debug + 300605 idmn + 300606 ssrv + 300607 vpnserver + 300608 samserver + 300609 sams_server + 300610 chrysalis + 300611 ddm + 300612 ddm-is + 300613 mx-bcp-debug + 300614 upmrd + 300615 upmdsd + 300616 res + 300617 colortron + 300618 zrs + 300619 afpsrv + 300620 apxft + 300621 nrp + 300622 hpid + 300623 mailwatch + 300624 fos bc_fcrb_receiver + + + +Thurlow Standards Track [Page 47] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + 300625 cs_sysadmin_svr + 300626 cs_controller_svr + 300627 nokia_nms_eai + 300628 dbg + 300629 remex + 300630 cs_bind + 300631 idm + 300632 prpasswd + 300633 iw-pw + 300634 starrb + 300635 Impress_Server + 300636 colorstar + 300637 gwugui + 300638 gwsgui + 300639 dai_command_proxy + 300640 dai_alarm_server + 300641 dai_fui_proxy + 300642 spai_command_proxy + 300643 spai_alarm_server + 300644 iris + 300645 hcxttp + 300646 updatedb rsched + 300647 urnd urn + 300648 iqwpsrv + 300649 dskutild + 300650 online + 300651 nlserv + 300652 acsm + 300653 dg_clar_sormsg + 300654 wwpollerrpc + 300655 wwmodelrpc + 300656 nsprofd + 300657 nsdistd + 300658 recollect + 300659 lssexecd lss_res + 300660 lssagend lss_rea + 300661 cdinfo + 300662 sninsr_addon + 300663 mm-sap + 300664 ks + 300665 psched + 300666 tekdvfs + 300667 storxll + 300668 nisse + 300669 lbadvise + 300670 atcinstaller + 300671 atntstarter + 300672 NetML + + + +Thurlow Standards Track [Page 48] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + 300673 tdmesmge + 300674 tdmesmgd + 300675 tdmesmgt + 300676 olm + 300677 mediamanagement + 300678 rdbprog fieldowsrv + 300679 rpwdprog rpwd + 300680 sapi-trace + 300681 sapi-master-daemon + 300682 omdcuprog om-dcu + 300683 wwprocmon + 300684 tndidprog + 300685 rkey_setsecretprog + 300686 asdu_server_prog + 300687 pwrcntrl + 300688 siunixd + 300689 wmapi + 300690 cross_reference_ole + 300691 rtc + 300692 disp + 300693 sql_compilation_agent + 300694 tnsysprog + 300695 ius-sapimd + 300696 apteam-dx + 300697 rmsrpc + 300698 seismic_system + 300699 remote + 300700 tt1_ts_event nokia_nms + 300701 fxrs + 300702 onlicense + 300703 vxkey + 300704 dinis + 300705 sched2d schedule-2 + 300706 sched3d schedule-3 + 300707 sched4d schedule-4 + 300708 sched5d schedule-5 + 300709 sched6d schedule-6 + 300710 sched7d schedule-7 + 300711 sched8d schedule-8 + 300712 sched9d schedule-9 + 300713 adtsqry + 300714 adserv + 300715 adrepserv + 300716 [unknown] + 300717 caad + 300718 caaui + 300719 cescda + 300720 vcapiadmin + + + +Thurlow Standards Track [Page 49] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + 300721 vcapi20 + 300722 tcfs + 300723 csed + 300724 nothand + 300725 hacb + 300726 nfauth + 300727 imlm + 300728 bestcomm + 300729 lprpasswd + 300730 rprpasswd + 300731 proplistd + 300732 mikomomc + 300733 arepa-cas + 300734 [unknown] + 300735 [unknown] + 300736 ando_ts + 300737 intermezzo + 300738 ftel-sdh-request + 300739 ftel-sdh-response + 300740 [unknown] + 300741 [unknown] + 300742 [unknown] + 300743 [unknown] + 300744 [unknown] + 300745 vrc_abb + 300746 vrc_comau + 300747 vrc_fanuc + 300748 vrc_kuka + 300749 vrc_reis + 300750 hp_sv6d + 300751 correntmgr01 + 300752 correntike + 300753 [unknown] + 300754 [unknown] + 300755 intransa_location + 300756 intransa_management + 300757 intransa_federation + 300758 portprot + 300759 ipmiprot + 300760 aceapi + 300761 f6000pss + 300762 vsmapi_program + 300763 ubertuple + 300764 ctconcrpcif + 300765 mfuadmin + 300766 aiols + 300767 dsmrootd + 300768 htdl + + + +Thurlow Standards Track [Page 50] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + 300769 caba + 300770 vrc_cosimir + 300771 cmhelmd + 300772 polynsm + 300773 [unknown] + 300774 [unknown] + 300775 [unknown] + 300776 [unknown] + 300777 [unknown] + 300778 [unknown] + 300779 [unknown] + 300780 [unknown] + 300781 dsmrecalld + 300782 [unknown] + 300783 [unknown] + 300784 twrgcontrol + 300785 twrled + 300786 twrcfgdb + BMC software 300787-300886 + unassigned 300887 - 300999 + Sun Microsystems 301000-302000 [ 2000 numbers ] + unassigned 302001-349999 + American Airlines 350000 - 350999 + Acucobol Inc. 351000 - 351099 + The Bristol Group 351100 - 351249 + Amteva Technologies 351250 - 351349 + 351350 wfmMgmtApp + 351351 wfmMgmtDataSrv + 351352 wfmMgmtFut1 + 351353 wfmMgmtFut1 + 351354 wfmAPM + 351355 wfmIAMgr + 351356 wfmECMgr + 351357 wfmLookOut + 351358 wfmAgentFut1 + 351359 wfmAgentFut2 + unassigned 351360 - 351406 + Sterling Software ITD 351407 csed + 351360 sched10d + 351361 sched11d + 351362 sched12d + 351363 sched13d + 351364 sched14d + 351365 sched15d + 351366 sched16d + 351367 sched17d + 351368 sched18d + 351369 sched19d + + + +Thurlow Standards Track [Page 51] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + 351370 sched20d + 351371 sched21d + 351372 sched22d + 351373 sched23d + 351374 sched24d + 351375 sched25d + 351376 sched26d + 351377 sched27d + 351378 sched28d + 351379 sched29d + 351380 sched30d + 351381 sched31d + 351382 sched32d + 351383 sched33d + 351384 sched34d + 351385 sched35d + 351386 sched36d + 351387 sched37d + 351388 sched38d + 351389 sched39d + 351390 consoleserver + 351391 scheduleserver + 351392 RDELIVER + 351393 REVENTPROG + 351394 RSENDEVENTPROG + 351395 snapp + 351396 snapad + 351397 sdsoodb + 351398 sdsmain + 351399 sdssrv + 351400 sdsclnt + 351401 sdsreg + 351402 fsbatch + 351403 fsmonitor + 351404 fsdisp + 351405 fssession + 351406 fslog + 351407 svdpappserv + 351408 gns + 351409 [unkonwn] + 351410 [unkonwn] + 351411 [unkonwn] + 351412 axi + 351413 rpcxfr + 351414 slm + 351415 smbpasswdd + 351416 tbdbserv + 351417 tbprojserv + + + +Thurlow Standards Track [Page 52] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + 351418 genericserver + 351419 dynarc_ds + 351420 dnscmdr + 351421 ipcmdr + 351422 faild + 351423 failmon + 351424 faildebug + 351425 [unknown] + 351426 [unknown] + 351427 siemens_srs + 351428 bsproxy + 351429 ifsrpc + 351430 CesPvcSm + 351431 FrPvcSm + 351432 AtmPvcSm + 351433 radius + 351434 auditor + 351435 sft + 351436 voicemail + 351437 kis + 351438 SOFTSERV_NOTIFY + 351439 dynarpc + 351440 hc + 351441 iopas + 351442 iopcs + 351443 iopss + 351444 spcnfs + 351445 spcvss + 351446 matilda_sms + 351447 matilda_brs + 351448 matilda_dbs + 351449 matilda_sps + 351450 matilda_svs + 351451 matilda_sds + 351452 matilda_vvs + 351453 matilda_stats + 351454 xtrade + 351455 mapsvr + 351456 hp_graphicsd + 351457 berkeley_db + berkeley_db_svc + 351458 io_server + 351459 rpc.niod + 351460 rpc.kill + 351461 hmdisproxy + 351462 smdisproxy + 351463 avatard + 351464 namu + + + +Thurlow Standards Track [Page 53] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + 351465 BMCSess + 351466 FENS_Sport + 351467 EM_CONFIG + 351468 EM_CONFIG_RESP + 351469 lodge_proof + 351470 ARCserveIT-Queue + 351471 ARCserveIT-Device + 351472 ARCserveIT-Discover + 351473 ARCserveIT-Alert + 351474 ARCserveIT-Database + 351475 scand1 + 351476 scand2 + 351477 scand3 + 351478 scand4 + 351479 scand5 + 351480 dscv + 351481 cb_svc + 351482 [unknown] + 351483 iprobe + 351484 omniconf + 351485 isan + BG Partners 351486 - 351500 + 351501 mond + 351502 iqlremote + 351503 iqlalarm + unassigned 351504 - 351599 + Orion Multisystems 351600-351855 + unassigned 351856 - 351899 + NSP lab 351900 - 351999 + unassigned 351999 - 352232 + 352233 asautostart + 352234 asmediad1 + 352235 asmediad2 + 352236 asmediad3 + 352237 asmediad4 + 352238 asmediad5 + 352239 asmediad6 + 352240 asmediad7 + 352241 asmediad8 + 352242 asmediad9 + 352243 asmediad10 + 352244 asmediad11 + 352245 asmediad12 + 352246 asmediad13 + 352247 asmediad14 + 352248 asmediad15 + 352249 asmediad16 + 352250 waruser + + + +Thurlow Standards Track [Page 54] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + 352251 warlogd + 352252 warsvrmgr + 352253 warvfsysd + 352254 warftpd + 352255 warnfsd + 352256 bofproxyc0 + 352257 bofproxys0 + 352258 bofproxyc1 + 352259 bofproxys1 + 352260 bofproxyc2 + 352261 bofproxys2 + 352262 bofproxyc3 + 352263 bofproxys3 + 352264 bofproxyc4 + 352265 bofproxys4 + 352266 bofproxyc5 + 352267 bofproxys5 + 352268 bofproxyc6 + 352269 bofproxys6 + 352270 bofproxyc7 + 352271 bofproxys7 + 352272 bofproxyc8 + 352273 bofproxys8 + 352274 bofproxyc9 + 352275 bofproxys9 + 352276 bofproxyca + 352277 bofproxysa + 352278 bofproxycb + 352279 bofproxysb + 352280 bofproxycc + 352281 bofproxysc + 352282 bofproxycd + 352283 bofproxysd + 352284 bofproxyce + 352285 bofproxyse + 352286 bofproxycf + 352287 bofproxysf + 352288 bofproxypo0 + 352289 bofproxypo1 + 352290 bofproxypo2 + 352291 bofproxypo3 + 352292 bofproxypo4 + unassigned 352293-370000 + 370001 [unknown] + 370002 [unknown] + 370003 [unknown] + 370004 [unknown] + 370005 [unknown] + + + +Thurlow Standards Track [Page 55] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + 370006 [unknown] + 370007 [unknown] + 370008 [unknown] + 370009 [unknown] + 370010 [unknown] + 370011 [unknown] + 370012 [unknown] + 370013 [unknown] + 370014 [unknown] + 370015 [unknown] + 370016 [unknown] + 370017 [unknown] + 370018 [unknown] + 370019 [unknown] + 370020 [unknown] + 370021 [unknown] + 370022 [unknown] + 370023 [unknown] + 370024 [unknown] + 370025 [unknown] + 370026 [unknown] + 370027 [unknown] + unassigned 370028 - 379999 + 380000 opensna + 380001 probenet + 380002 [unknown] + 380003 license + 380004 na.3com-remote + 380005 na.ntp + 380006 probeutil + 380007 na.vlb + 380008 cds_mhs_agent + 380009 cds_x500_agent + 380010 cds_mailhub_agent + 380011 codex_6500_proxy + 380012 codex_6500_trapd + 380013 na.nm212 + 380014 cds_mta_metrics_agent + 380015 [unkonwn] + 380016 na.caple + 380017 codexcapletrap + Swiss Re 380018-380028 + 380029 ncstat + 380030 ncnfsstat + 380031 ftams + 380032 na.isotp + 380033 na.rfc1006 + unassigned 380034 - 389999 + + + +Thurlow Standards Track [Page 56] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + Epoch Systems 390000 - 390049 + Quickturn Systems 390050 - 390065 + Team One Systems 390066 - 390075 + General Electric CRD 390076 - 390085 + TSIG NFS subcommittee 390086 - 390089 + SoftLab ab 390090 - 390099 + Legato Network Services 390100 - 390115 + 390116 cdsmonitor + 390117 cdslock + 390118 cdslicense + 390119 shm + 390120 rws + 390121 cdc + Data General 390122 - 390141 + Perfect Byte 390142 - 390171 + JTS Computer Systems 390172 - 390181 + Parametric Technology 390182 - 390191 + Voxem 390192 - 390199 + Effix Systems 390200 - 390299 + Motorola 390300 - 390309 + Mobile Data Intl. 390310 - 390325 + Physikalisches Institut 390326 - 390330 + Ergon Informatik AG 390331 - 390340 + Analog Devices Inc. 390341 - 390348 + Interphase Corporation 390349 - 390358 + NeWsware 390359 - 390374 + Qualix Group 390375 - 390379 + Xerox Imaging Systems 390380 - 390389 + Noble Net 390390 - 390399 + Legato Network Services 390400 - 390499 + Client Server Tech. 390500 - 390511 + Atria 390512 - 390517 + GE NMR Instruments 390518 - 390525 + Harris Corp. 390526 - 390530 + Unisys 390531 - 390562 + Aggregate Computing 390563 - 390572 + Interactive Data 390573 - 390580 + OKG AB 390581 - 390589 + K2 Software 390591 - 390594 + Collier Jackson 390595 - 390599 + Remedy Corporation 390600 - 390699 + Mentor Graphics 390700 - 390799 + AT&T Bell Labs (Lucent) 390800 - 390899 + Xerox 390900 - 390999 + Silicon Graphics 391000 - 391063 + Data General 391064 - 391095 + Computer Support Corp. 391096 - 391099 + Quorum Software Systems 391100 - 391199 + + + +Thurlow Standards Track [Page 57] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + InterLinear Technology 391200 - 391209 + Highland Software 391210 - 391229 + Boeing Comp. Svcs. 391230 - 391249 + IBM Sweden 391250 - 391259 + Signature Authority Svc 391260 - 391271 + ZUMTOBEL Licht GmbH 391272 - 391283 + NOAA/ERL 391284 - 391299 + NCR Corp. 391300 - 391399 + FTP Software 391400 - 391409 + Cadre Technologies 391410 - 391433 + Visionware Ltd (UK) 391434 - 391439 + IBR-Partner AG 391440 - 391449 + CAP Programator AB 391450 - 391459 + Reichle+De-Massari AG 391460 - 391474 + Swiss Bank Corp (London) 391475 - 391484 + Unisys Enterprise Svr 391485 - 391489 + Intel - Test Dev. Tech. 391490 - 391499 + Ampex 391500 - 391755 + 391756 naas-spare + 391757 naas-admin + 391758 isps + 391759 isps-admin + 391760 mars + 391761 mars-admin + 391762 attcis_spare0 + 391763 attcis_spare1 + 391764 mail-server + 391765 mail-server-spare + 391766 attcis_spare2 + 391767 attcis_spare3 + 391768 attcis_spare4 + 391769 attcis_spare5 + 391770 attcis_spare6 + 391771 attcis_spare7 + Integrated Systems, Inc. 391772 - 391779 + Parametric Tech., Inc. 391780 - 391789 + Ericsson Telecom AB 391790 - 391799 + SLAC 391800 - 391849 + 391850 qhrdata + 391851 qhrbackup + 391852 minutedata + 391853 prefecture + 391854 supc + 391855 suadmincrw + 391856 suadminotas + 391857 sumessage + 391858 sublock + 391859 sumotd + + + +Thurlow Standards Track [Page 58] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + staffware dev. (uk) 391860 - 391869 + Staffware Dev. (UK) 391870 - 391879 + 391880 namesrvr + 391881 disksrvr + 391882 tapesrvr + 391883 migsrvr + 391884 pdmsrvr + 391885 pvrsrvr + 391886 repacksrvr + 391887 [unknown] + Convex Computer Corp. 391888 - 391951 + 391952 lookoutsrv + 391953 lookoutagnt + 391954 lookoutprxy + 391955 lookoutsnmp + 391956 lookoutrmon + 391957 lookoutfut1 + 391958 lookoutfut2 + windward 391959 - 391967 + 391968 sra_legato + 391969 sra_legato_imgsvr + 391970 sra_legato_0 + 391971 sra_legato_1 + 391972 sra_legato_2 + 391973 sra_legato_3 + 391974 sra_legato_4 + 391975 sra_legato_5 + 391976 sra_legato_6 + 391977 sra_legato_7 + 391978 sra_legato_8 + 391979 sra_legato_9 + Brooktree Corp. 391980 - 391989 + Cadence Design Systems 391990 - 391999 + J. Frank & Associates 392000 - 392999 + Cooperative Solutions 393000 - 393999 + Xerox Corp. 394000 - 395023 + 395024 odbc_sqlretriever + 3M 395025 - 395091 + Digital Zone Intl. 395092 - 395099 + Software Professionals 395100 - 395159 + Del Mar Solutions 395160 - 395164 + 395165 ife-es + 395166 ife-resmgr + 395167 ife-aes + 395168 ife-bite + 395169 ife-loader + 395170 ife-satcom + 395171 ife-seat + + + +Thurlow Standards Track [Page 59] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + 395172 ife-dbmgr + 395173 ife-testmgr + 395174 atrium_server + 395175 ase_director + 395176 ase_agent + 395177 ase_hsm + 395178 ase_mgr + 395179 ase_sim + Hewlett-Packard 395180 - 395194 + XES, Inc. 395195 - 395199 + Unitech Products 395200 - 395249 + TransSys 395250 - 395505 + Unisys Govt Systems 395506 - 395519 + Bellcore 395520 - 395529 + IBM 395530 - 395561 + AT&T Network Services 395562 - 395571 + Data General 395572 - 395577 + Swiss Bank Corp 395578 - 395597 + Swiss Bank Corp 395598 - 395637 + Novell 395638 - 395643 + Computer Associates 395644 - 395650 + Omneon Video Networks 395651 - 395656 + unassigned 395657 - 395908 + UK Post Office 395909 - 395924 + AEROSPATIALE 395925 - 395944 + Result d.o.o. 395945 - 395964 + DataTools, Inc. 395965 - 395980 + CADIS, Inc. 395981 - 395990 + Cummings Group, Inc. 395991 - 395994 + Cadre Technologies 395995 - 395999 + American Airlines 396000 - 396999 + Ericsson Telecom TM Div 397000 - 398023 + IBM 398024 - 398028 + Toshiba OME Works 398029 - 398033 + TUSC Computer Systems 398034 - 398289 + AT&T 398290 - 398320 + Ontario Hydro 398321 - 398346 + Micrion Corporation 398347 - 398364 + unassigned 398365 - 398591 + Pegasystems, Inc. 398592 - 399616 + Spectra Securities Soft 399617 - 399850 + QualCom 399851 - 399866 + unassigned 399867 - 399884 + Altris Software Ltd. 399885 - 399899 + ISO/IEC WG11 399900 - 399919 + Parametric Technology 399920 - 399949 + Dolby Laboratories 399950 - 399981 + unassigned 399982 - 399991 + + + +Thurlow Standards Track [Page 60] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + Xerox PARC 399992 - 399999 + # + Next Inc. 200100000 - 200199999 + Netwise (RPCtool) 200200000 + Concurrent Computer Corp 200200001 - 200200007 + AIM Technology 200300000 - 200399999 + TGV 200400000 - 200499999 + # + # Sun-assigned authentication flavor numbers + # + AUTH_NONE 0 /* no authentication, see RFC 1831 */ + /* a.k.a. AUTH_NULL */ + AUTH_SYS 1 /* unix style (uid+gids), RFC 1831 */ + /* a.k.a. AUTH_UNIX */ + AUTH_SHORT 2 /* short hand unix style, RFC 1831 */ + AUTH_DH 3 /* des style (encrypted timestamp) */ + /* a.k.a. AUTH_DES, see RFC 2695 */ + AUTH_KERB 4 /* kerberos auth, see RFC 2695 */ + AUTH_RSA 5 /* RSA authentication */ + RPCSEC_GSS 6 /* GSS-based RPC security for auth, + integrity and privacy, RPC 5403 */ + + AUTH_NW 30001 NETWARE + AUTH_SEC 200000 TSIG NFS subcommittee + AUTH_ESV 200004 SVr4 ES + + AUTH_NQNFS 300000 Univ. of Guelph - Not Quite NFS + AUTH_GSSAPI 300001 OpenVision + AUTH_ILU_UGEN 300002 Xerox + - ILU Unsecured Generic Identity + # + # Small blocks are assigned out of the 39xxxx series of numbers + # + AUTH_SPNEGO 390000 + 390000 - 390255 NFS 'pseudo' flavors for RPCSEC_GSS + 390003 - kerberos_v5 authentication, RFC 2623 + 390004 - kerberos_v5 with data integrity, RFC 2623 + 390005 - kerberos_v5 with data privacy, RFC 2623 + + 200000000 Reserved + 200100000 NeXT Inc. + + + + + + + + + + +Thurlow Standards Track [Page 61] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + +Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2203] Eisler, M., Chiu, A., and L. Ling, "RPCSEC_GSS Protocol + Specification", RFC 2203, September 1997. + + [RFC4506] Eisler, M., Ed., "XDR: External Data Representation + Standard", STD 67, RFC 4506, May 2006. + +Informative References + + [DH] Diffie & Hellman, "New Directions in Cryptography", IEEE + Transactions on Information Theory IT-22, November 1976. + + [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, + August 1980. + + [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, RFC + 793, September 1981. + + [RFC1094] Sun Microsystems, "NFS: Network File System Protocol + specification", RFC 1094, March 1989. + + [RFC1813] Callaghan, B., Pawlowski, B., and P. Staubach, "NFS + Version 3 Protocol Specification", RFC 1813, June 1995. + + [RFC1831] Srinivasan, R., "RPC: Remote Procedure Call Protocol + Specification Version 2", RFC 1831, August 1995. + + [RFC1833] Srinivasan, R., "Binding Protocols for ONC RPC Version 2", + RFC 1833, August 1995. + + [RFC2623] Eisler, M., "NFS Version 2 and Version 3 Security Issues + and the NFS Protocol's Use of RPCSEC_GSS and Kerberos V5", + RFC 2623, June 1999. + + [RFC2695] Chiu, A., "Authentication Mechanisms for ONC RPC", RFC + 2695, September 1999. + + [RFC2743] Linn, J., "Generic Security Service Application Program + Interface Version 2, Update 1", RFC 2743, January 2000. + + [RFC3530] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., + Beame, C., Eisler, M., and D. Noveck, "Network File System + (NFS) version 4 Protocol", RFC 3530, April 2003. + + + + +Thurlow Standards Track [Page 62] + +RFC 5531 Remote Procedure Call Protocol Version 2 May 2009 + + + [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an + IANA Considerations Section in RFCs", BCP 26, RFC 5226, + May 2008. + + [VMTP] Cheriton, D., "VMTP: Versatile Message Transaction + Protocol", Preliminary Version 0.3, Stanford University, + January 1987. + + [XRPC] Birrell, A. D. & B. J. Nelson, "Implementing Remote + Procedure Calls", XEROX CSL-83-7, October 1983. + +Author's Address + + Robert Thurlow + Sun Microsystems, Inc. + 500 Eldorado Boulevard, UBRM05-171 + Broomfield, CO 80021 + + Phone: 877-718-3419 + EMail: robert.thurlow@sun.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Thurlow Standards Track [Page 63] + \ No newline at end of file diff --git a/src/rpc/constants.ts b/src/rpc/constants.ts new file mode 100644 index 00000000..65a8d9af --- /dev/null +++ b/src/rpc/constants.ts @@ -0,0 +1,105 @@ +/** + * ONC RPC Protocol Constants + * Supports RFC 1057, RFC 1831, and RFC 5531 + */ + +/** + * Message type enumeration + * @see RFC 1057 Section 8 + * @see RFC 1831 Section 8 + * @see RFC 5531 Section 9 + */ +export const enum RpcMsgType { + CALL = 0, + REPLY = 1, +} + +/** + * Reply status enumeration + * @see RFC 1057 Section 8 + * @see RFC 1831 Section 8 + * @see RFC 5531 Section 9 + */ +export const enum RpcReplyStat { + MSG_ACCEPTED = 0, + MSG_DENIED = 1, +} + +/** + * Accept status values for accepted RPC replies + * @see RFC 1057 Section 8 (values 0-4) + * @see RFC 1831 Section 8 (values 0-4) + * @see RFC 5531 Section 9 (added SYSTEM_ERR = 5) + */ +export const enum RpcAcceptStat { + SUCCESS = 0, // RFC 1057 + PROG_UNAVAIL = 1, // RFC 1057 + PROG_MISMATCH = 2, // RFC 1057 + PROC_UNAVAIL = 3, // RFC 1057 + GARBAGE_ARGS = 4, // RFC 1057 + SYSTEM_ERR = 5, // RFC 5531 +} + +/** + * Reject status enumeration + * @see RFC 1057 Section 8 + * @see RFC 1831 Section 8 + * @see RFC 5531 Section 9 + */ +export const enum RpcRejectStat { + RPC_MISMATCH = 0, + AUTH_ERROR = 1, +} + +/** + * Authentication status values for rejected RPC calls + * @see RFC 1057 Section 9 (values 1-5) + * @see RFC 1831 Section 9 (values 1-5) + * @see RFC 5531 Section 10 (expanded with values 0, 6-14 for RPCSEC_GSS support) + */ +export const enum RpcAuthStat { + AUTH_OK = 0, // RFC 5531 + AUTH_BADCRED = 1, // RFC 1057 + AUTH_REJECTEDCRED = 2, // RFC 1057 + AUTH_BADVERF = 3, // RFC 1057 + AUTH_REJECTEDVERF = 4, // RFC 1057 + AUTH_TOOWEAK = 5, // RFC 1057 + AUTH_INVALIDRESP = 6, // RFC 5531 + AUTH_FAILED = 7, // RFC 5531 + AUTH_KERB_GENERIC = 8, // RFC 5531 + AUTH_TIMEEXPIRE = 9, // RFC 5531 + AUTH_TKT_FILE = 10, // RFC 5531 + AUTH_DECODE = 11, // RFC 5531 + AUTH_NET_ADDR = 12, // RFC 5531 + RPCSEC_GSS_CREDPROBLEM = 13, // RFC 5531 + RPCSEC_GSS_CTXPROBLEM = 14, // RFC 5531 +} + +/** + * Authentication flavor numbers + * @see RFC 1057 Section 9 (AUTH_NULL, AUTH_UNIX, AUTH_SHORT, AUTH_DES) + * @see RFC 1831 Section 9, Appendix A (renamed AUTH_NULL->AUTH_NONE, AUTH_UNIX->AUTH_SYS) + * @see RFC 5531 Section 10, Appendix C (added AUTH_KERB, AUTH_RSA, RPCSEC_GSS) + * + * Note: Old names (AUTH_NULL, AUTH_UNIX, AUTH_DES) maintained for backward compatibility + */ +export const enum RpcAuthFlavor { + AUTH_NONE = 0, // RFC 1831 (renamed from AUTH_NULL in RFC 1057) + AUTH_SYS = 1, // RFC 1831 (renamed from AUTH_UNIX in RFC 1057) + AUTH_SHORT = 2, // RFC 1057 + AUTH_DH = 3, // RFC 5531 (obsolete, was AUTH_DES in RFC 1057) + AUTH_KERB = 4, // RFC 5531 + AUTH_RSA = 5, // RFC 5531 + RPCSEC_GSS = 6, // RFC 5531 (RFC 2203, RFC 5403) + AUTH_NULL = 0, // RFC 1057 (alias for AUTH_NONE) + AUTH_UNIX = 1, // RFC 1057 (alias for AUTH_SYS) + AUTH_DES = 3, // RFC 1057 (alias for AUTH_DH) +} + +/** + * RPC protocol version (all RFCs use version 2) + * @see RFC 1057 Section 8 + * @see RFC 1831 Section 8 + * @see RFC 5531 Section 9 + */ +export const RPC_VERSION = 2; diff --git a/src/rpc/errors.ts b/src/rpc/errors.ts new file mode 100644 index 00000000..e3c894b5 --- /dev/null +++ b/src/rpc/errors.ts @@ -0,0 +1,11 @@ +export class RpcDecodingError extends Error { + constructor(message = 'RPC_DECODING') { + super(message); + } +} + +export class RpcEncodingError extends Error { + constructor(message = 'RPC_ENCODING') { + super(message); + } +} diff --git a/src/rpc/index.ts b/src/rpc/index.ts new file mode 100644 index 00000000..2e5d483b --- /dev/null +++ b/src/rpc/index.ts @@ -0,0 +1,5 @@ +export * from './constants'; +export * from './errors'; +export * from './messages'; +export * from './RpcMessageDecoder'; +export * from './RpcMessageEncoder'; diff --git a/src/rpc/messages.ts b/src/rpc/messages.ts new file mode 100644 index 00000000..78c1b014 --- /dev/null +++ b/src/rpc/messages.ts @@ -0,0 +1,52 @@ +import type {Reader} from '@jsonjoy.com/buffers/lib/Reader'; +import type {RpcAuthFlavor, RpcAcceptStat, RpcRejectStat, RpcAuthStat} from './constants'; + +export {RpcMsgType, RpcReplyStat, RpcAcceptStat, RpcRejectStat, RpcAuthStat, RpcAuthFlavor} from './constants'; + +export class RpcOpaqueAuth { + constructor( + public readonly flavor: RpcAuthFlavor, + public readonly body: Reader, + ) {} +} + +export class RpcMismatchInfo { + constructor( + public readonly low: number, + public readonly high: number, + ) {} +} + +export class RpcCallMessage { + constructor( + public readonly xid: number, + public readonly rpcvers: number, + public readonly prog: number, + public readonly vers: number, + public readonly proc: number, + public readonly cred: RpcOpaqueAuth, + public readonly verf: RpcOpaqueAuth, + public params: Reader | undefined = undefined, + ) {} +} + +export class RpcAcceptedReplyMessage { + constructor( + public readonly xid: number, + public readonly verf: RpcOpaqueAuth, + public readonly stat: RpcAcceptStat, + public readonly mismatchInfo?: RpcMismatchInfo, + public results: Reader | undefined = undefined, + ) {} +} + +export class RpcRejectedReplyMessage { + constructor( + public readonly xid: number, + public readonly stat: RpcRejectStat, + public readonly mismatchInfo?: RpcMismatchInfo, + public readonly authStat?: RpcAuthStat, + ) {} +} + +export type RpcMessage = RpcCallMessage | RpcAcceptedReplyMessage | RpcRejectedReplyMessage; diff --git a/src/ws/WsFrameDecoder.ts b/src/ws/WsFrameDecoder.ts index 4b7a76ef..2d5cd278 100644 --- a/src/ws/WsFrameDecoder.ts +++ b/src/ws/WsFrameDecoder.ts @@ -1,4 +1,4 @@ -import {StreamingOctetReader} from '@jsonjoy.com/util/lib/buffers/StreamingOctetReader'; +import {StreamingOctetReader} from '@jsonjoy.com/buffers/lib/StreamingOctetReader'; import {WsFrameOpcode} from './constants'; import {WsFrameDecodingError} from './errors'; import {WsCloseFrame, WsFrameHeader, WsPingFrame, WsPongFrame} from './frames'; diff --git a/src/ws/index.ts b/src/ws/index.ts index ddd48ff8..6344b429 100644 --- a/src/ws/index.ts +++ b/src/ws/index.ts @@ -2,3 +2,4 @@ export * from './constants'; export * from './errors'; export * from './frames'; export * from './WsFrameDecoder'; +export * from './WsFrameEncoder'; diff --git a/src/xdr/README.md b/src/xdr/README.md new file mode 100644 index 00000000..f9866d02 --- /dev/null +++ b/src/xdr/README.md @@ -0,0 +1,302 @@ +# XDR Quick Reference Guide + +## RFC Version Support + +| Feature | RFC 1014 | RFC 1832 | RFC 4506 | Status | +| ----------------------------- | -------- | -------- | -------- | -------------- | +| Basic types (int, bool, enum) | ✅ | ✅ | ✅ | ✅ Implemented | +| Hyper integers (64-bit) | ✅ | ✅ | ✅ | ✅ Implemented | +| Float, Double | ✅ | ✅ | ✅ | ✅ Implemented | +| Quadruple (128-bit float) | ❌ | ✅ | ✅ | ⚠️ Type only | +| Opaque, String | ✅ | ✅ | ✅ | ✅ Implemented | +| Array, Struct, Union | ✅ | ✅ | ✅ | ✅ Implemented | +| Optional-data | ❌ | ✅ | ✅ | ✅ Implemented | +| Security guidelines | ❌ | ❌ | ✅ | ✅ Implemented | + +## Data Type Quick Reference + +### Primitive Types + +```typescript +// Integer types +{ type: 'int' } // 32-bit signed: -2^31 to 2^31-1 +{ type: 'unsigned_int' } // 32-bit unsigned: 0 to 2^32-1 +{ type: 'hyper' } // 64-bit signed +{ type: 'unsigned_hyper' } // 64-bit unsigned +{ type: 'boolean' } // Encoded as int (0/1) + +// Floating-point types +{ type: 'float' } // IEEE 754 single-precision (32-bit) +{ type: 'double' } // IEEE 754 double-precision (64-bit) +{ type: 'quadruple' } // IEEE 754 quad-precision (128-bit) - not implemented + +// Special types +{ type: 'void' } // No data +{ type: 'enum', values: { RED: 0, GREEN: 1 } } +``` + +### Composite Types + +```typescript +// Fixed-length opaque data +{ type: 'opaque', size: 16 } + +// Variable-length opaque data (max size optional) +{ type: 'vopaque' } +{ type: 'vopaque', size: 1024 } + +// String (max size optional) +{ type: 'string' } +{ type: 'string', size: 255 } + +// Fixed-length array +{ type: 'array', elements: { type: 'int' }, size: 10 } + +// Variable-length array (max size optional) +{ type: 'varray', elements: { type: 'int' } } +{ type: 'varray', elements: { type: 'int' }, size: 100 } + +// Struct +{ + type: 'struct', + fields: [ + [{ type: 'int' }, 'id'], + [{ type: 'string' }, 'name'] + ] +} + +// Union +{ + type: 'union', + arms: [ + [0, { type: 'int' }], + [1, { type: 'string' }] + ], + default?: { type: 'void' } +} + +// Optional-data (NEW in RFC 1832) +{ type: 'optional', element: { type: 'int' } } +``` + +## Usage Examples + +### Basic Encoding/Decoding + +```typescript +import {XdrEncoder, XdrDecoder, Writer, Reader} from '@jsonjoy.com/json-pack'; + +// Encode +const writer = new Writer(); +const encoder = new XdrEncoder(writer); +encoder.writeInt(42); +encoder.writeString('hello'); +const encoded = writer.flush(); + +// Decode +const reader = new Reader(); +const decoder = new XdrDecoder(reader); +reader.reset(encoded); +const num = decoder.readInt(); // 42 +const str = decoder.readString(); // "hello" +``` + +### Schema-Based Encoding/Decoding + +```typescript +import {XdrSchemaEncoder, XdrSchemaDecoder, Writer, Reader} from '@jsonjoy.com/json-pack'; + +const schema = { + type: 'struct', + fields: [ + [{type: 'int'}, 'id'], + [{type: 'string', size: 100}, 'name'], + [{type: 'boolean'}, 'active'], + ], +}; + +// Encode +const writer = new Writer(); +const encoder = new XdrSchemaEncoder(writer); +const data = {id: 1, name: 'Alice', active: true}; +const encoded = encoder.encode(data, schema); + +// Decode +const reader = new Reader(); +const decoder = new XdrSchemaDecoder(reader); +const decoded = decoder.decode(encoded, schema); +// { id: 1, name: 'Alice', active: true } +``` + +### Optional-Data (RFC 1832) + +```typescript +const schema = { + type: 'optional', + element: {type: 'int'}, +}; + +// Encode optional value +encoder.writeOptional(42, schema); // Encodes: TRUE + 42 +encoder.writeOptional(null, schema); // Encodes: FALSE +encoder.writeOptional(undefined, schema); // Encodes: FALSE + +// Decode optional value +const value = decoder.readOptional(schema); // number | null +``` + +### Union Types + +```typescript +import {XdrUnion} from '@jsonjoy.com/json-pack'; + +const schema = { + type: 'union', + arms: [ + [0, {type: 'int'}], + [1, {type: 'string'}], + ], +}; + +// Encode union +const intValue = new XdrUnion(0, 42); +const strValue = new XdrUnion(1, 'hello'); +encoder.encode(intValue, schema); + +// Decode union +const decoded = decoder.decode(data, schema); // XdrUnion instance +console.log(decoded.discriminant); // 0 or 1 +console.log(decoded.value); // 42 or "hello" +``` + +### Schema Validation + +```typescript +import {XdrSchemaValidator} from '@jsonjoy.com/json-pack'; + +const validator = new XdrSchemaValidator(); + +// Validate schema structure +const isValidSchema = validator.validateSchema(schema); // boolean + +// Validate value against schema +const isValidValue = validator.validateValue(data, schema); // boolean +``` + +## Security Best Practices + +### Always Use Size Limits + +```typescript +// ❌ Bad - no maximum size +{ type: 'string' } +{ type: 'varray', elements: { type: 'int' } } + +// ✅ Good - explicit maximum size +{ type: 'string', size: 1024 } +{ type: 'varray', elements: { type: 'int' }, size: 100 } +``` + +### Validate Before Encoding + +```typescript +const validator = new XdrSchemaValidator(); +if (!validator.validateValue(data, schema)) { + throw new Error('Invalid data for schema'); +} +encoder.encode(data, schema); +``` + +### Implement Depth Limits + +```typescript +class SafeDecoder extends XdrSchemaDecoder { + private depth = 0; + private maxDepth = 100; + + decode(data: Uint8Array, schema: XdrSchema): unknown { + if (++this.depth > this.maxDepth) { + throw new Error('Max depth exceeded'); + } + try { + return super.decode(data, schema); + } finally { + this.depth--; + } + } +} +``` + +## Common Patterns + +### Enum Pattern + +```typescript +const ColorEnum = { + type: 'enum', + values: { + RED: 0, + GREEN: 1, + BLUE: 2, + }, +} as const; + +encoder.writeEnum('RED', ColorEnum); +const color = decoder.readEnum(ColorEnum); // 'RED' | 0 +``` + +### Struct Pattern + +```typescript +interface User { + id: number; + name: string; + email: string; + active: boolean; +} + +const UserSchema = { + type: 'struct', + fields: [ + [{type: 'int'}, 'id'], + [{type: 'string', size: 100}, 'name'], + [{type: 'string', size: 255}, 'email'], + [{type: 'boolean'}, 'active'], + ], +} as const; +``` + +### Variable-Length Array Pattern + +```typescript +const ListSchema = { + type: 'varray', + elements: {type: 'int'}, + size: 1000, // max 1000 elements +}; + +encoder.encode([1, 2, 3, 4, 5], ListSchema); +``` + +## Performance Tips + +1. **Reuse encoder/decoder instances** - avoid creating new ones per operation +2. **Use fixed-size types** when possible - faster than variable-length +3. **Preallocate buffers** for known sizes +4. **Batch operations** - encode multiple values before flushing +5. **Use schema validation** only in development/testing + +## Interoperability + +This implementation is wire-compatible with: + +- Sun RPC (ONC RPC) +- NFS (Network File System) +- Other RFC 4506-compliant libraries in any language + +## Further Reading + +- [SECURITY.md](./SECURITY.md) - Security considerations and best practices +- [RFC_COMPLIANCE.md](./RFC_COMPLIANCE.md) - Detailed RFC compliance information +- [CHANGELOG.md](./CHANGELOG.md) - Recent changes and additions +- [RFC 4506](https://datatracker.ietf.org/doc/html/rfc4506) - Current XDR standard diff --git a/src/xdr/XdrDecoder.ts b/src/xdr/XdrDecoder.ts index 6e158d13..142d1b6a 100644 --- a/src/xdr/XdrDecoder.ts +++ b/src/xdr/XdrDecoder.ts @@ -30,7 +30,7 @@ export class XdrDecoder(size: number, elementReader: () => T): T[] { const array: T[] = []; - for (let i = 0; i < size; i++) { - array.push(elementReader()); - } + for (let i = 0; i < size; i++) array.push(elementReader()); return array; } diff --git a/src/xdr/XdrEncoder.ts b/src/xdr/XdrEncoder.ts index fba2681d..3d32d7bf 100644 --- a/src/xdr/XdrEncoder.ts +++ b/src/xdr/XdrEncoder.ts @@ -102,7 +102,6 @@ export class XdrEncoder implements BinaryJsonEncoder { public writeHyper(hyper: number | bigint): void { const writer = this.writer; writer.ensureCapacity(8); - if (typeof hyper === 'bigint') { writer.view.setBigInt64(writer.x, hyper, false); // big-endian } else { @@ -171,15 +170,9 @@ export class XdrEncoder implements BinaryJsonEncoder { const writer = this.writer; const paddedSize = Math.ceil(size / 4) * 4; writer.ensureCapacity(paddedSize); - - // Write data writer.buf(data, size); - - // Write padding bytes const padding = paddedSize - size; - for (let i = 0; i < padding; i++) { - writer.u8(0); - } + for (let i = 0; i < padding; i++) writer.u8(0); } /** @@ -202,13 +195,9 @@ export class XdrEncoder implements BinaryJsonEncoder { const lengthOffset = writer.x; writer.x += 4; // Reserve space for length const bytesWritten = writer.utf8(str); - - // Calculate and write padding const paddedSize = Math.ceil(bytesWritten / 4) * 4; const padding = paddedSize - bytesWritten; - for (let i = 0; i < padding; i++) { - writer.u8(0); - } + for (let i = 0; i < padding; i++) writer.u8(0); // Go back and write the actual byte length const currentPos = writer.x; @@ -232,14 +221,9 @@ export class XdrEncoder implements BinaryJsonEncoder { */ public writeNumber(num: number): void { if (Number.isInteger(num)) { - if (num >= -2147483648 && num <= 2147483647) { - this.writeInt(num); - } else { - this.writeHyper(num); - } - } else { - this.writeDouble(num); - } + if (num >= -2147483648 && num <= 2147483647) this.writeInt(num); + else this.writeHyper(num); + } else this.writeDouble(num); } /** diff --git a/src/xdr/XdrSchemaDecoder.ts b/src/xdr/XdrSchemaDecoder.ts index ef1910c1..37a5653b 100644 --- a/src/xdr/XdrSchemaDecoder.ts +++ b/src/xdr/XdrSchemaDecoder.ts @@ -4,9 +4,6 @@ import {XdrUnion} from './XdrUnion'; import type {IReader, IReaderResettable} from '@jsonjoy.com/buffers/lib'; import type { XdrSchema, - XdrPrimitiveSchema, - XdrWidePrimitiveSchema, - XdrCompositeSchema, XdrEnumSchema, XdrOpaqueSchema, XdrVarlenOpaqueSchema, @@ -15,6 +12,7 @@ import type { XdrVarlenArraySchema, XdrStructSchema, XdrUnionSchema, + XdrOptionalSchema, } from './types'; /** @@ -81,6 +79,11 @@ export class XdrSchemaDecoder { return this.readStruct(schema as XdrStructSchema); case 'union': return this.readUnion(schema as XdrUnionSchema); + case 'optional': + return this.readOptional(schema as XdrOptionalSchema); + case 'const': + // Constants are not decoded; they have no runtime representation + return undefined; default: throw new Error(`Unknown schema type: ${(schema as any).type}`); @@ -196,4 +199,15 @@ export class XdrSchemaDecoder { throw new Error(`No matching union arm for discriminant: ${discriminant}`); } + + /** + * Reads optional-data according to the optional schema (RFC 1832 Section 3.19). + * Optional-data is syntactic sugar for a union with boolean discriminant. + * Returns null if opted is FALSE, otherwise returns the decoded value. + */ + private readOptional(schema: XdrOptionalSchema): unknown | null { + const opted = this.decoder.readBoolean(); + if (!opted) return null; + return this.readValue(schema.element); + } } diff --git a/src/xdr/XdrSchemaEncoder.ts b/src/xdr/XdrSchemaEncoder.ts index ca9c21fa..790466b7 100644 --- a/src/xdr/XdrSchemaEncoder.ts +++ b/src/xdr/XdrSchemaEncoder.ts @@ -11,6 +11,7 @@ import type { XdrVarlenArraySchema, XdrStructSchema, XdrUnionSchema, + XdrOptionalSchema, } from './types'; export class XdrSchemaEncoder { @@ -86,10 +87,16 @@ export class XdrSchemaEncoder { } if (!(value in schema.values)) { - throw new Error(`Invalid enum value: ${value}`); + throw new Error(`Invalid enum value: ${value}. Valid values are: ${Object.keys(schema.values).join(', ')}`); } - this.encoder.writeInt(schema.values[value]); + const enumValue = schema.values[value]; + // Per RFC 4506 Section 4.3: "It is an error to encode as an enum any integer other than those that have been given assignments" + if (!Number.isInteger(enumValue)) { + throw new Error(`Enum value ${value} has non-integer assignment: ${enumValue}`); + } + + this.encoder.writeInt(enumValue); } public writeOpaque(value: Uint8Array, schema: XdrOpaqueSchema): void { @@ -189,6 +196,24 @@ export class XdrSchemaEncoder { } } + /** + * Writes optional-data value (RFC 1832 Section 3.19). + * Optional-data is syntactic sugar for a union with boolean discriminant. + * If value is null/undefined, writes FALSE; otherwise writes TRUE and the value. + */ + public writeOptional(value: unknown, schema: XdrOptionalSchema): void { + if (schema.type !== 'optional') { + throw new Error('Schema is not an optional schema'); + } + + if (value === null || value === undefined) { + this.encoder.writeBoolean(false); + } else { + this.encoder.writeBoolean(true); + this.writeValue(value, schema.element); + } + } + public writeNumber(value: number, schema: XdrSchema): void { switch (schema.type) { case 'int': @@ -274,6 +299,12 @@ export class XdrSchemaEncoder { throw new Error('Union values must be wrapped in XdrUnion class'); } break; + case 'optional': + this.writeOptional(value, schema as XdrOptionalSchema); + break; + case 'const': + // Constants are not encoded; they are compile-time values + break; default: throw new Error(`Unknown schema type: ${(schema as any).type}`); } diff --git a/src/xdr/XdrSchemaValidator.ts b/src/xdr/XdrSchemaValidator.ts index 3ce652dc..3742bf82 100644 --- a/src/xdr/XdrSchemaValidator.ts +++ b/src/xdr/XdrSchemaValidator.ts @@ -1,8 +1,5 @@ import type { XdrSchema, - XdrPrimitiveSchema, - XdrWidePrimitiveSchema, - XdrCompositeSchema, XdrEnumSchema, XdrOpaqueSchema, XdrVarlenOpaqueSchema, @@ -11,6 +8,8 @@ import type { XdrVarlenArraySchema, XdrStructSchema, XdrUnionSchema, + XdrOptionalSchema, + XdrConstantSchema, } from './types'; /** @@ -83,6 +82,12 @@ export class XdrSchemaValidator { case 'union': return this.validateUnionSchema(schema as XdrUnionSchema); + case 'optional': + return this.validateOptionalSchema(schema as XdrOptionalSchema); + + case 'const': + return this.validateConstantSchema(schema as XdrConstantSchema); + default: return false; } @@ -203,6 +208,22 @@ export class XdrSchemaValidator { return true; } + private validateOptionalSchema(schema: XdrOptionalSchema): boolean { + if (!schema.element) { + return false; + } + + return this.validateSchemaInternal(schema.element); + } + + private validateConstantSchema(schema: XdrConstantSchema): boolean { + if (typeof schema.value !== 'number' || !Number.isInteger(schema.value)) { + return false; + } + + return true; + } + private validateValueInternal(value: unknown, schema: XdrSchema): boolean { switch (schema.type) { case 'void': @@ -282,6 +303,15 @@ export class XdrSchemaValidator { const matchesDefault = unionSchema.default ? this.validateValueInternal(value, unionSchema.default) : false; return matchesArm || matchesDefault; + case 'optional': + const optionalSchema = schema as XdrOptionalSchema; + // Optional values can be null/undefined or match the element schema + return value === null || value === undefined || this.validateValueInternal(value, optionalSchema.element); + + case 'const': + // Constants have no runtime value validation + return true; + default: return false; } diff --git a/src/xdr/__tests__/RFC_SUMMARY.md b/src/xdr/__tests__/RFC_SUMMARY.md new file mode 100644 index 00000000..126ad629 --- /dev/null +++ b/src/xdr/__tests__/RFC_SUMMARY.md @@ -0,0 +1,27 @@ +### Overview + +There are multiple iterations of the External Data Representation (XDR) codec specifications, primarily documented in three RFCs: RFC 1014 (June 1987), RFC 1832 (August 1995), and RFC 4506 (May 2006). XDR is a standard for describing and encoding data in a machine-independent format, enabling portable data transfer across different computer architectures (e.g., big-endian vs. little-endian systems like SUN WORKSTATION, VAX, IBM-PC, and Cray). It operates at the ISO presentation layer, using implicit typing and a C-like language for data descriptions. All versions maintain core principles: big-endian byte order, 4-byte alignment with zero-padding, and support for common data types from high-level languages. RFC 1832 obsoleted RFC 1014 to reflect deployment experiences and add features like quadruple-precision floating-point. RFC 4506 obsoleted RFC 1832 with no technical changes to the protocol but added IANA considerations, security guidance, and minor corrections. While other RFCs (e.g., RFC 7531 for NFSv4.0 XDR descriptions) reference or embed XDR for specific protocols, they do not redefine the core XDR standard. + +### Key Differences Between RFC 1014 and RFC 1832 + +RFC 1832 updated the XDR standard based on real-world deployment, formalizing elements, adding new data types, and clarifying encodings without breaking compatibility. It obsoleted RFC 1014 by providing a more precise and comprehensive specification. Notable changes include: + +- **Addition of Quadruple-Precision Floating-Point**: Introduced a new 128-bit type (quadruple) with a 1-bit sign, 15-bit biased exponent (bias 16383), and 112-bit fraction, analogous to IEEE double-extended format. This was absent in RFC 1014, which only supported 32-bit float and 64-bit double. +- **Enhanced Floating-Point Details**: Expanded on IEEE 754-1985 compliance, including explicit definitions for NaN (signaling/quiet, system-dependent), signed zero, infinity, and denormals/subnormals in appendices. RFC 1014 provided basic float/double descriptions but with less detail on edge cases. +- **Formalization of Optional-Data Type**: Newly defined special syntax (`type-name *identifier;`) for handling optional or recursive data (e.g., linked lists), equivalent to a bool-discriminated union or variable-length array<1>. This improved clarity over RFC 1014's implicit equivalents. +- **Language and Syntax Updates**: More precise extended Backus-Naur Form (BNF) grammar, lexical rules (e.g., comments, whitespace, case-sensitive identifiers), and constraints (e.g., unsigned constants for sizes, unique names in structs/unions, integer-only discriminants). Added preferred typedef syntax for struct/enum/union declarations. RFC 1014 had a similar but less detailed language spec. +- **Areas for Future Enhancement**: Explicit section noting lacks (e.g., bit fields, bitmaps, packed decimals) and potential extensions (variable block sizes/byte orders), not present in RFC 1014. +- **Discussion and Examples**: Expanded rationale for design choices (e.g., 4-byte units, no explicit typing); added a full "file" structure example with hex/ASCII encoding. Updated references (e.g., added RFC 1831 for ONC RPC) and trademarks. +- **Status Changes**: Advanced to Standards Track; added security considerations (none substantive); clarified assumptions like portable bytes. +- Core elements like data types (int, hyper, opaque, string, arrays, structures, unions, void), big-endian order, and 4-byte padding remained consistent, but RFC 1832 emphasized deployment status and resolved ambiguities. + +### Key Differences Between RFC 1832 and RFC 4506 + +RFC 4506 made no technical alterations to the XDR wire format, data types, or encoding rules, ensuring full backward compatibility. It obsoleted RFC 1832 primarily for administrative updates, reflecting IETF practices, and added non-normative guidance. Key updates include: + +- **IANA Considerations**: New section requiring standards-track RFCs for adding data types, with documentation in the RFC Editor's database. No immediate IANA registries were established, unlike RFC 1832's lack of such provisions. +- **Security Considerations**: Expanded to highlight risks such as buffer overflows (recommend explicit bounds with ""), memory leaks from nul octets in strings, illegal characters (e.g., '/' in filenames), and denial-of-service via recursive structures (suggest non-recursive decoders or limits). Emphasized that protocols like NFSv4 handle higher-level security. RFC 1832 had minimal security notes. +- **References**: Distinguished normative (only IEEE 754-1985) from informative (added [KERN], [COHE], etc.); reproduced full IEEE definitions for convenience, including quadruple-precision analogs. +- **Minor Corrections**: Fixed errors identified by reviewers (e.g., Peter Astrand, Bryan Olson) from RFC 1832, such as clarifications in descriptions. +- **Additional Sections**: Updated trademarks/owners list; expanded acknowledgements to credit original contributors like Bob Lyon and Raj Srinivasan. +- All core features—data types (including quadruple), encoding rules (big-endian, 4-byte alignment, zero-padding), language syntax, and examples—remained identical to RFC 1832. diff --git a/src/xdr/__tests__/XdrDecoder.spec.ts b/src/xdr/__tests__/XdrDecoder.spec.ts index 18974191..91a3bf1e 100644 --- a/src/xdr/__tests__/XdrDecoder.spec.ts +++ b/src/xdr/__tests__/XdrDecoder.spec.ts @@ -278,12 +278,12 @@ describe('XdrDecoder', () => { describe('decode method', () => { test('decode method calls readAny which throws', () => { const encoded = new Uint8Array([0, 0, 0, 42]); - expect(() => decoder.decode(encoded)).toThrow('XdrDecoder.readAny() requires explicit type methods'); + expect(() => decoder.decode(encoded)).toThrow('not implemented'); }); test('read method calls readAny which throws', () => { const encoded = new Uint8Array([0, 0, 0, 42]); - expect(() => decoder.read(encoded)).toThrow('XdrDecoder.readAny() requires explicit type methods'); + expect(() => decoder.read(encoded)).toThrow('not implemented'); }); }); diff --git a/src/xdr/__tests__/rfc1014.txt b/src/xdr/__tests__/rfc1014.txt new file mode 100644 index 00000000..fbbcc91f --- /dev/null +++ b/src/xdr/__tests__/rfc1014.txt @@ -0,0 +1,1118 @@ + +Network Working Group Sun Microsystems, Inc. +Request for Comments: 1014 June 1987 + + + XDR: External Data Representation Standard + +STATUS OF THIS MEMO + + This RFC describes a standard that Sun Microsystems, Inc., and others + are using, one we wish to propose for the Internet's consideration. + Distribution of this memo is unlimited. + +1. INTRODUCTION + + XDR is a standard for the description and encoding of data. It is + useful for transferring data between different computer + architectures, and has been used to communicate data between such + diverse machines as the SUN WORKSTATION*, VAX*, IBM-PC*, and Cray*. + XDR fits into the ISO presentation layer, and is roughly analogous in + purpose to X.409, ISO Abstract Syntax Notation. The major difference + between these two is that XDR uses implicit typing, while X.409 uses + explicit typing. + + XDR uses a language to describe data formats. The language can only + be used only to describe data; it is not a programming language. + This language allows one to describe intricate data formats in a + concise manner. The alternative of using graphical representations + (itself an informal language) quickly becomes incomprehensible when + faced with complexity. The XDR language itself is similar to the C + language [1], just as Courier [4] is similar to Mesa. Protocols such + as Sun RPC (Remote Procedure Call) and the NFS* (Network File System) + use XDR to describe the format of their data. + + The XDR standard makes the following assumption: that bytes (or + octets) are portable, where a byte is defined to be 8 bits of data. + A given hardware device should encode the bytes onto the various + media in such a way that other hardware devices may decode the bytes + without loss of meaning. For example, the Ethernet* standard + suggests that bytes be encoded in "little-endian" style [2], or least + significant bit first. + +2. BASIC BLOCK SIZE + + The representation of all items requires a multiple of four bytes (or + 32 bits) of data. The bytes are numbered 0 through n-1. The bytes + are read or written to some byte stream such that byte m always + precedes byte m+1. If the n bytes needed to contain the data are not + a multiple of four, then the n bytes are followed by enough (0 to 3) + + + +SUN Microsystems [Page 1] + +RFC 1014 External Data Representation June 1987 + + + residual zero bytes, r, to make the total byte count a multiple of 4. + + We include the familiar graphic box notation for illustration and + comparison. In most illustrations, each box (delimited by a plus + sign at the 4 corners and vertical bars and dashes) depicts a byte. + Ellipses (...) between boxes show zero or more additional bytes where + required. + + +--------+--------+...+--------+--------+...+--------+ + | byte 0 | byte 1 |...|byte n-1| 0 |...| 0 | BLOCK + +--------+--------+...+--------+--------+...+--------+ + |<-----------n bytes---------->|<------r bytes------>| + |<-----------n+r (where (n+r) mod 4 = 0)>----------->| + +3. XDR DATA TYPES + + Each of the sections that follow describes a data type defined in the + XDR standard, shows how it is declared in the language, and includes + a graphic illustration of its encoding. + + For each data type in the language we show a general paradigm + declaration. Note that angle brackets (< and >) denote + variablelength sequences of data and square brackets ([ and ]) denote + fixed-length sequences of data. "n", "m" and "r" denote integers. + For the full language specification and more formal definitions of + terms such as "identifier" and "declaration", refer to section 5: + "The XDR Language Specification". + + For some data types, more specific examples are included. A more + extensive example of a data description is in section 6: "An Example + of an XDR Data Description". + +3.1 Integer + + An XDR signed integer is a 32-bit datum that encodes an integer in + the range [-2147483648,2147483647]. The integer is represented in + two's complement notation. The most and least significant bytes are + 0 and 3, respectively. Integers are declared as follows: + + int identifier; + + (MSB) (LSB) + +-------+-------+-------+-------+ + |byte 0 |byte 1 |byte 2 |byte 3 | INTEGER + +-------+-------+-------+-------+ + <------------32 bits------------> + + + + + +SUN Microsystems [Page 2] + +RFC 1014 External Data Representation June 1987 + + +3.2.Unsigned Integer + + An XDR unsigned integer is a 32-bit datum that encodes a nonnegative + integer in the range [0,4294967295]. It is represented by an + unsigned binary number whose most and least significant bytes are 0 + and 3, respectively. An unsigned integer is declared as follows: + + unsigned int identifier; + + (MSB) (LSB) + +-------+-------+-------+-------+ + |byte 0 |byte 1 |byte 2 |byte 3 | UNSIGNED INTEGER + +-------+-------+-------+-------+ + <------------32 bits------------> + +3.3 Enumeration + + Enumerations have the same representation as signed integers. + Enumerations are handy for describing subsets of the integers. + Enumerated data is declared as follows: + + enum { name-identifier = constant, ... } identifier; + + For example, the three colors red, yellow, and blue could be + described by an enumerated type: + + enum { RED = 2, YELLOW = 3, BLUE = 5 } colors; + + It is an error to encode as an enum any other integer than those that + have been given assignments in the enum declaration. + +3.4 Boolean + + Booleans are important enough and occur frequently enough to warrant + their own explicit type in the standard. Booleans are declared as + follows: + + bool identifier; + + This is equivalent to: + + enum { FALSE = 0, TRUE = 1 } identifier; + + + + + + + + + +SUN Microsystems [Page 3] + +RFC 1014 External Data Representation June 1987 + + +3.5 Hyper Integer and Unsigned Hyper Integer + + The standard also defines 64-bit (8-byte) numbers called hyper + integer and unsigned hyper integer. Their representations are the + obvious extensions of integer and unsigned integer defined above. + They are represented in two's complement notation. The most and + least significant bytes are 0 and 7, respectively. Their + declarations: + + hyper identifier; unsigned hyper identifier; + + (MSB) (LSB) + +-------+-------+-------+-------+-------+-------+-------+-------+ + |byte 0 |byte 1 |byte 2 |byte 3 |byte 4 |byte 5 |byte 6 |byte 7 | + +-------+-------+-------+-------+-------+-------+-------+-------+ + <----------------------------64 bits----------------------------> + HYPER INTEGER + UNSIGNED HYPER INTEGER + +3.6 Floating-point + + The standard defines the floating-point data type "float" (32 bits or + 4 bytes). The encoding used is the IEEE standard for normalized + single-precision floating-point numbers [3]. The following three + fields describe the single-precision floating-point number: + + S: The sign of the number. Values 0 and 1 represent positive and + negative, respectively. One bit. + + E: The exponent of the number, base 2. 8 bits are devoted to this + field. The exponent is biased by 127. + + F: The fractional part of the number's mantissa, base 2. 23 bits + are devoted to this field. + + Therefore, the floating-point number is described by: + + (-1)**S * 2**(E-Bias) * 1.F + + + + + + + + + + + + + +SUN Microsystems [Page 4] + +RFC 1014 External Data Representation June 1987 + + + It is declared as follows: + float identifier; + + +-------+-------+-------+-------+ + |byte 0 |byte 1 |byte 2 |byte 3 | SINGLE-PRECISION + S| E | F | FLOATING-POINT NUMBER + +-------+-------+-------+-------+ + 1|<- 8 ->|<-------23 bits------>| + <------------32 bits------------> + + Just as the most and least significant bytes of a number are 0 and 3, + the most and least significant bits of a single-precision floating- + point number are 0 and 31. The beginning bit (and most significant + bit) offsets of S, E, and F are 0, 1, and 9, respectively. Note that + these numbers refer to the mathematical positions of the bits, and + NOT to their actual physical locations (which vary from medium to + medium). + + The EEE specifications should be consulted concerning the encoding + for signed zero, signed infinity (overflow), and denormalized numbers + (underflow) [3]. According to IEEE specifications, the "NaN" (not a + number) is system dependent and should not be used externally. + +3.7 Double-precision Floating-point + + The standard defines the encoding for the double-precision floating- + point data type "double" (64 bits or 8 bytes). The encoding used is + the IEEE standard for normalized double-precision floating-point + numbers [3]. The standard encodes the following three fields, which + describe the double-precision floating-point number: + + S: The sign of the number. Values 0 and 1 represent positive and + negative, respectively. One bit. + + E: The exponent of the number, base 2. 11 bits are devoted to + this field. The exponent is biased by 1023. + + F: The fractional part of the number's mantissa, base 2. 52 bits + are devoted to this field. + + Therefore, the floating-point number is described by: + + (-1)**S * 2**(E-Bias) * 1.F + + + + + + + + +SUN Microsystems [Page 5] + +RFC 1014 External Data Representation June 1987 + + + It is declared as follows: + + double identifier; + + +------+------+------+------+------+------+------+------+ + |byte 0|byte 1|byte 2|byte 3|byte 4|byte 5|byte 6|byte 7| + S| E | F | + +------+------+------+------+------+------+------+------+ + 1|<--11-->|<-----------------52 bits------------------->| + <-----------------------64 bits-------------------------> + DOUBLE-PRECISION FLOATING-POINT + + Just as the most and least significant bytes of a number are 0 and 3, + the most and least significant bits of a double-precision floating- + point number are 0 and 63. The beginning bit (and most significant + bit) offsets of S, E , and F are 0, 1, and 12, respectively. Note + that these numbers refer to the mathematical positions of the bits, + and NOT to their actual physical locations (which vary from medium to + medium). + + The IEEE specifications should be consulted concerning the encoding + for signed zero, signed infinity (overflow), and denormalized numbers + (underflow) [3]. According to IEEE specifications, the "NaN" (not a + number) is system dependent and should not be used externally. + +3.8 Fixed-length Opaque Data + + At times, fixed-length uninterpreted data needs to be passed among + machines. This data is called "opaque" and is declared as follows: + + opaque identifier[n]; + + where the constant n is the (static) number of bytes necessary to + contain the opaque data. If n is not a multiple of four, then the n + bytes are followed by enough (0 to 3) residual zero bytes, r, to make + the total byte count of the opaque object a multiple of four. + + 0 1 ... + +--------+--------+...+--------+--------+...+--------+ + | byte 0 | byte 1 |...|byte n-1| 0 |...| 0 | + +--------+--------+...+--------+--------+...+--------+ + |<-----------n bytes---------->|<------r bytes------>| + |<-----------n+r (where (n+r) mod 4 = 0)------------>| + FIXED-LENGTH OPAQUE + +3.9 Variable-length Opaque Data + + The standard also provides for variable-length (counted) opaque data, + + + +SUN Microsystems [Page 6] + +RFC 1014 External Data Representation June 1987 + + + defined as a sequence of n (numbered 0 through n-1) arbitrary bytes + to be the number n encoded as an unsigned integer (as described + below), and followed by the n bytes of the sequence. + + Byte m of the sequence always precedes byte m+1 of the sequence, and + byte 0 of the sequence always follows the sequence's length (count). + If n is not a multiple of four, then the n bytes are followed by + enough (0 to 3) residual zero bytes, r, to make the total byte count + a multiple of four. Variable-length opaque data is declared in the + following way: + + opaque identifier; + or + opaque identifier<>; + + The constant m denotes an upper bound of the number of bytes that the + sequence may contain. If m is not specified, as in the second + declaration, it is assumed to be (2**32) - 1, the maximum length. + The constant m would normally be found in a protocol specification. + For example, a filing protocol may state that the maximum data + transfer size is 8192 bytes, as follows: + + opaque filedata<8192>; + + 0 1 2 3 4 5 ... + +-----+-----+-----+-----+-----+-----+...+-----+-----+...+-----+ + | length n |byte0|byte1|...| n-1 | 0 |...| 0 | + +-----+-----+-----+-----+-----+-----+...+-----+-----+...+-----+ + |<-------4 bytes------->|<------n bytes------>|<---r bytes--->| + |<----n+r (where (n+r) mod 4 = 0)---->| + VARIABLE-LENGTH OPAQUE + + It is an error to encode a length greater than the maximum described + in the specification. + +3.10 String + + The standard defines a string of n (numbered 0 through n-1) ASCII + bytes to be the number n encoded as an unsigned integer (as described + above), and followed by the n bytes of the string. Byte m of the + string always precedes byte m+1 of the string, and byte 0 of the + string always follows the string's length. If n is not a multiple of + four, then the n bytes are followed by enough (0 to 3) residual zero + bytes, r, to make the total byte count a multiple of four. Counted + byte strings are declared as follows: + + + + + + +SUN Microsystems [Page 7] + +RFC 1014 External Data Representation June 1987 + + + string object; + or + string object<>; + + + The constant m denotes an upper bound of the number of bytes that a + string may contain. If m is not specified, as in the second + declaration, it is assumed to be (2**32) - 1, the maximum length. + The constant m would normally be found in a protocol specification. + For example, a filing protocol may state that a file name can be no + longer than 255 bytes, as follows: + + string filename<255>; + + 0 1 2 3 4 5 ... + +-----+-----+-----+-----+-----+-----+...+-----+-----+...+-----+ + | length n |byte0|byte1|...| n-1 | 0 |...| 0 | + +-----+-----+-----+-----+-----+-----+...+-----+-----+...+-----+ + |<-------4 bytes------->|<------n bytes------>|<---r bytes--->| + |<----n+r (where (n+r) mod 4 = 0)---->| + STRING + + It is an error to encode a length greater than the maximum described + in the specification. + +3.11 Fixed-length Array + + Declarations for fixed-length arrays of homogeneous elements are in + the following form: + + type-name identifier[n]; + + Fixed-length arrays of elements numbered 0 through n-1 are encoded by + individually encoding the elements of the array in their natural + order, 0 through n-1. Each element's size is a multiple of four + bytes. Though all elements are of the same type, the elements may + have different sizes. For example, in a fixed-length array of + strings, all elements are of type "string", yet each element will + vary in its length. + + +---+---+---+---+---+---+---+---+...+---+---+---+---+ + | element 0 | element 1 |...| element n-1 | + +---+---+---+---+---+---+---+---+...+---+---+---+---+ + |<--------------------n elements------------------->| + + FIXED-LENGTH ARRAY + + + + + +SUN Microsystems [Page 8] + +RFC 1014 External Data Representation June 1987 + + +3.12 Variable-length Array + + Counted arrays provide the ability to encode variable-length arrays + of homogeneous elements. The array is encoded as the element count n + (an unsigned integer) followed by the encoding of each of the array's + elements, starting with element 0 and progressing through element n- + 1. The declaration for variable-length arrays follows this form: + + type-name identifier; + or + type-name identifier<>; + + The constant m specifies the maximum acceptable element count of an + array; if m is not specified, as in the second declaration, it is + assumed to be (2**32) - 1. + + 0 1 2 3 + +--+--+--+--+--+--+--+--+--+--+--+--+...+--+--+--+--+ + | n | element 0 | element 1 |...|element n-1| + +--+--+--+--+--+--+--+--+--+--+--+--+...+--+--+--+--+ + |<-4 bytes->|<--------------n elements------------->| + COUNTED ARRAY + + It is an error to encode a value of n that is greater than the + maximum described in the specification. + +3.13 Structure + + Structures are declared as follows: + + struct { + component-declaration-A; + component-declaration-B; + ... + } identifier; + + The components of the structure are encoded in the order of their + declaration in the structure. Each component's size is a multiple of + four bytes, though the components may be different sizes. + + +-------------+-------------+... + | component A | component B |... STRUCTURE + +-------------+-------------+... + +3.14 Discriminated Union + + A discriminated union is a type composed of a discriminant followed + by a type selected from a set of prearranged types according to the + + + +SUN Microsystems [Page 9] + +RFC 1014 External Data Representation June 1987 + + + value of the discriminant. The type of discriminant is either "int", + "unsigned int", or an enumerated type, such as "bool". The component + types are called "arms" of the union, and are preceded by the value + of the discriminant which implies their encoding. Discriminated + unions are declared as follows: + + union switch (discriminant-declaration) { + case discriminant-value-A: + arm-declaration-A; + case discriminant-value-B: + arm-declaration-B; + ... + default: default-declaration; + } identifier; + + Each "case" keyword is followed by a legal value of the discriminant. + The default arm is optional. If it is not specified, then a valid + encoding of the union cannot take on unspecified discriminant values. + The size of the implied arm is always a multiple of four bytes. + + The discriminated union is encoded as its discriminant followed by + the encoding of the implied arm. + + 0 1 2 3 + +---+---+---+---+---+---+---+---+ + | discriminant | implied arm | DISCRIMINATED UNION + +---+---+---+---+---+---+---+---+ + |<---4 bytes--->| + +3.15 Void + + An XDR void is a 0-byte quantity. Voids are useful for describing + operations that take no data as input or no data as output. They are + also useful in unions, where some arms may contain data and others do + not. The declaration is simply as follows: + void; + + Voids are illustrated as follows: + + ++ + || VOID + ++ + --><-- 0 bytes + +3.16 Constant + + The data declaration for a constant follows this form: + + + + +SUN Microsystems [Page 10] + +RFC 1014 External Data Representation June 1987 + + + const name-identifier = n; + + "const" is used to define a symbolic name for a constant; it does not + declare any data. The symbolic constant may be used anywhere a + regular constant may be used. For example, the following defines a + symbolic constant DOZEN, equal to 12. + + const DOZEN = 12; + +3.17 Typedef + + "typedef" does not declare any data either, but serves to define new + identifiers for declaring data. The syntax is: + + typedef declaration; + + The new type name is actually the variable name in the declaration + part of the typedef. For example, the following defines a new type + called "eggbox" using an existing type called "egg": + + typedef egg eggbox[DOZEN]; + + Variables declared using the new type name have the same type as the + new type name would have in the typedef, if it was considered a + variable. For example, the following two declarations are equivalent + in declaring the variable "fresheggs": + + eggbox fresheggs; + egg fresheggs[DOZEN]; + + When a typedef involves a struct, enum, or union definition, there is + another (preferred) syntax that may be used to define the same type. + In general, a typedef of the following form: + + typedef <> identifier; + + may be converted to the alternative form by removing the "typedef" + part and placing the identifier after the "struct", "union", or + "enum" keyword, instead of at the end. For example, here are the two + ways to define the type "bool": + + + + + + + + + + + +SUN Microsystems [Page 11] + +RFC 1014 External Data Representation June 1987 + + + typedef enum { /* using typedef */ + FALSE = 0, + TRUE = 1 + } bool; + + enum bool { /* preferred alternative */ + FALSE = 0, + TRUE = 1 + }; + + The reason this syntax is preferred is one does not have to wait + until the end of a declaration to figure out the name of the new + type. + +3.18 Optional-data + + Optional-data is one kind of union that occurs so frequently that we + give it a special syntax of its own for declaring it. It is declared + as follows: + + type-name *identifier; + + This is equivalent to the following union: + + union switch (bool opted) { + case TRUE: + type-name element; + case FALSE: + void; + } identifier; + + It is also equivalent to the following variable-length array + declaration, since the boolean "opted" can be interpreted as the + length of the array: + + type-name identifier<1>; + + Optional-data is not so interesting in itself, but it is very useful + for describing recursive data-structures such as linked-lists and + trees. For example, the following defines a type "stringlist" that + encodes lists of arbitrary length strings: + + struct *stringlist { + string item<>; + stringlist next; + }; + + + + + +SUN Microsystems [Page 12] + +RFC 1014 External Data Representation June 1987 + + + It could have been equivalently declared as the following union: + + union stringlist switch (bool opted) { + case TRUE: + struct { + string item<>; + stringlist next; + } element; + case FALSE: + void; + }; + + or as a variable-length array: + + struct stringlist<1> { + string item<>; + stringlist next; + }; + + Both of these declarations obscure the intention of the stringlist + type, so the optional-data declaration is preferred over both of + them. The optional-data type also has a close correlation to how + recursive data structures are represented in high-level languages + such as Pascal or C by use of pointers. In fact, the syntax is the + same as that of the C language for pointers. + +3.19 Areas for Future Enhancement + + The XDR standard lacks representations for bit fields and bitmaps, + since the standard is based on bytes. Also missing are packed (or + binary-coded) decimals. + + The intent of the XDR standard was not to describe every kind of data + that people have ever sent or will ever want to send from machine to + machine. Rather, it only describes the most commonly used data-types + of high-level languages such as Pascal or C so that applications + written in these languages will be able to communicate easily over + some medium. + + One could imagine extensions to XDR that would let it describe almost + any existing protocol, such as TCP. The minimum necessary for this + are support for different block sizes and byte-orders. The XDR + discussed here could then be considered the 4-byte big-endian member + of a larger XDR family. + + + + + + + +SUN Microsystems [Page 13] + +RFC 1014 External Data Representation June 1987 + + +4. DISCUSSION + + (1) Why use a language for describing data? What's wrong with + diagrams? + + There are many advantages in using a data-description language such + as XDR versus using diagrams. Languages are more formal than + diagrams and lead to less ambiguous descriptions of data. + Languages are also easier to understand and allow one to think of + other issues instead of the low-level details of bit-encoding. + Also, there is a close analogy between the types of XDR and a + high-level language such as C or Pascal. This makes the + implementation of XDR encoding and decoding modules an easier task. + Finally, the language specification itself is an ASCII string that + can be passed from machine to machine to perform on-the-fly data + interpretation. + + (2) Why is there only one byte-order for an XDR unit? + + Supporting two byte-orderings requires a higher level protocol for + determining in which byte-order the data is encoded. Since XDR is + not a protocol, this can't be done. The advantage of this, though, + is that data in XDR format can be written to a magnetic tape, for + example, and any machine will be able to interpret it, since no + higher level protocol is necessary for determining the byte-order. + + (3) Why is the XDR byte-order big-endian instead of little-endian? + Isn't this unfair to little-endian machines such as the VAX(r), which + has to convert from one form to the other? + + Yes, it is unfair, but having only one byte-order means you have to + be unfair to somebody. Many architectures, such as the Motorola + 68000* and IBM 370*, support the big-endian byte-order. + + (4) Why is the XDR unit four bytes wide? + + There is a tradeoff in choosing the XDR unit size. Choosing a small + size such as two makes the encoded data small, but causes alignment + problems for machines that aren't aligned on these boundaries. A + large size such as eight means the data will be aligned on virtually + every machine, but causes the encoded data to grow too big. We chose + four as a compromise. Four is big enough to support most + architectures efficiently, except for rare machines such as the + eight-byte aligned Cray*. Four is also small enough to keep the + encoded data restricted to a reasonable size. + + + + + + +SUN Microsystems [Page 14] + +RFC 1014 External Data Representation June 1987 + + + (5) Why must variable-length data be padded with zeros? + + It is desirable that the same data encode into the same thing on all + machines, so that encoded data can be meaningfully compared or + checksummed. Forcing the padded bytes to be zero ensures this. + + (6) Why is there no explicit data-typing? + + Data-typing has a relatively high cost for what small advantages it + may have. One cost is the expansion of data due to the inserted type + fields. Another is the added cost of interpreting these type fields + and acting accordingly. And most protocols already know what type + they expect, so data-typing supplies only redundant information. + However, one can still get the benefits of data-typing using XDR. One + way is to encode two things: first a string which is the XDR data + description of the encoded data, and then the encoded data itself. + Another way is to assign a value to all the types in XDR, and then + define a universal type which takes this value as its discriminant + and for each value, describes the corresponding data type. + + +5. THE XDR LANGUAGE SPECIFICATION + + 5.1 Notational Conventions + + This specification uses an extended Back-Naur Form notation for + describing the XDR language. Here is a brief description of the + notation: + + + (1) The characters '|', '(', ')', '[', ']', '"', and '*' are special. + (2) Terminal symbols are strings of any characters surrounded by + double quotes. + (3) Non-terminal symbols are strings of non-special characters. + (4) Alternative items are separated by a vertical bar ("|"). + (5) Optional items are enclosed in brackets. + (6) Items are grouped together by enclosing them in parentheses. + (7) A '*' following an item means 0 or more occurrences of that item. + + For example, consider the following pattern: + + "a " "very" (", " "very")* [" cold " "and "] " rainy " + ("day" | "night") + + An infinite number of strings match this pattern. A few of them are: + + + + + + +SUN Microsystems [Page 15] + +RFC 1014 External Data Representation June 1987 + + + "a very rainy day" + "a very, very rainy day" + "a very cold and rainy day" + "a very, very, very cold and rainy night" + +5.2 Lexical Notes + + (1) Comments begin with '/*' and terminate with '*/'. + (2) White space serves to separate items and is otherwise ignored. + (3) An identifier is a letter followed by an optional sequence of + letters, digits or underbar ('_'). The case of identifiers is not + ignored. + (4) A constant is a sequence of one or more decimal digits, + optionally preceded by a minus-sign ('-'). + +5.3 Syntax Information + + declaration: + type-specifier identifier + | type-specifier identifier "[" value "]" + | type-specifier identifier "<" [ value ] ">" + | "opaque" identifier "[" value "]" + | "opaque" identifier "<" [ value ] ">" + | "string" identifier "<" [ value ] ">" + | type-specifier "*" identifier + | "void" + + value: + constant + | identifier + + type-specifier: + [ "unsigned" ] "int" + | [ "unsigned" ] "hyper" + | "float" + | "double" + | "bool" + | enum-type-spec + | struct-type-spec + | union-type-spec + | identifier + + enum-type-spec: + "enum" enum-body + + enum-body: + "{" + ( identifier "=" value ) + + + +SUN Microsystems [Page 16] + +RFC 1014 External Data Representation June 1987 + + + ( "," identifier "=" value )* + "}" + + struct-type-spec: + "struct" struct-body + + struct-body: + "{" + ( declaration ";" ) + ( declaration ";" )* + "}" + + union-type-spec: + "union" union-body + + union-body: + "switch" "(" declaration ")" "{" + ( "case" value ":" declaration ";" ) + ( "case" value ":" declaration ";" )* + [ "default" ":" declaration ";" ] + "}" + + constant-def: + "const" identifier "=" constant ";" + + type-def: + "typedef" declaration ";" + | "enum" identifier enum-body ";" + | "struct" identifier struct-body ";" + | "union" identifier union-body ";" + + definition: + type-def + | constant-def + + specification: + definition * + +5.4 Syntax Notes + + (1) The following are keywords and cannot be used as identifiers: + "bool", "case", "const", "default", "double", "enum", "float", + "hyper", "opaque", "string", "struct", "switch", "typedef", "union", + "unsigned" and "void". + + (2) Only unsigned constants may be used as size specifications for + arrays. If an identifier is used, it must have been declared + previously as an unsigned constant in a "const" definition. + + + +SUN Microsystems [Page 17] + +RFC 1014 External Data Representation June 1987 + + + (3) Constant and type identifiers within the scope of a specification + are in the same name space and must be declared uniquely within this + scope. + + (4) Similarly, variable names must be unique within the scope of + struct and union declarations. Nested struct and union declarations + create new scopes. + + (5) The discriminant of a union must be of a type that evaluates to + an integer. That is, "int", "unsigned int", "bool", an enumerated + type or any typedefed type that evaluates to one of these is legal. + Also, the case values must be one of the legal values of the + discriminant. Finally, a case value may not be specified more than + once within the scope of a union declaration. + +6. AN EXAMPLE OF AN XDR DATA DESCRIPTION + + Here is a short XDR data description of a thing called a "file", + which might be used to transfer files from one machine to another. + + const MAXUSERNAME = 32; /* max length of a user name */ + const MAXFILELEN = 65535; /* max length of a file */ + const MAXNAMELEN = 255; /* max length of a file name */ + + /* + * Types of files: + */ + enum filekind { + TEXT = 0, /* ascii data */ + DATA = 1, /* raw data */ + EXEC = 2 /* executable */ + }; + + /* + * File information, per kind of file: + */ + union filetype switch (filekind kind) { + case TEXT: + void; /* no extra information */ + case DATA: + string creator; /* data creator */ + case EXEC: + string interpretor; /* program interpretor */ + }; + + + + + + + +SUN Microsystems [Page 18] + +RFC 1014 External Data Representation June 1987 + + + /* + * A complete file: + */ + struct file { + string filename; /* name of file */ + filetype type; /* info about file */ + string owner; /* owner of file */ + opaque data; /* file data */ + }; + + Suppose now that there is a user named "john" who wants to store his + lisp program "sillyprog" that contains just the data "(quit)". His + file would be encoded as follows: + + OFFSET HEX BYTES ASCII COMMENTS + ------ --------- ----- -------- + 0 00 00 00 09 .... -- length of filename = 9 + 4 73 69 6c 6c sill -- filename characters + 8 79 70 72 6f ypro -- ... and more characters ... + 12 67 00 00 00 g... -- ... and 3 zero-bytes of fill + 16 00 00 00 02 .... -- filekind is EXEC = 2 + 20 00 00 00 04 .... -- length of interpretor = 4 + 24 6c 69 73 70 lisp -- interpretor characters + 28 00 00 00 04 .... -- length of owner = 4 + 32 6a 6f 68 6e john -- owner characters + 36 00 00 00 06 .... -- length of file data = 6 + 40 28 71 75 69 (qui -- file data bytes ... + 44 74 29 00 00 t).. -- ... and 2 zero-bytes of fill + +7. REFERENCES + + [1] Brian W. Kernighan & Dennis M. Ritchie, "The C Programming + Language", Bell Laboratories, Murray Hill, New Jersey, 1978. + + [2] Danny Cohen, "On Holy Wars and a Plea for Peace", IEEE Computer, + October 1981. + + [3] "IEEE Standard for Binary Floating-Point Arithmetic", ANSI/IEEE + Standard 754-1985, Institute of Electrical and Electronics + Engineers, August 1985. + + [4] "Courier: The Remote Procedure Call Protocol", XEROX + Corporation, XSIS 038112, December 1981. + + + + + + + + +SUN Microsystems [Page 19] + +RFC 1014 External Data Representation June 1987 + + +8. TRADEMARKS AND OWNERS + + SUN WORKSTATION Sun Microsystems, Inc. + VAX Digital Equipment Corporation + IBM-PC International Business Machines Corporation + Cray Cray Research + NFS Sun Microsystems, Inc. + Ethernet Xerox Corporation. + Motorola 68000 Motorola, Inc. + IBM 370 International Business Machines Corporation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +SUN Microsystems [Page 20] + diff --git a/src/xdr/__tests__/rfc1832.txt b/src/xdr/__tests__/rfc1832.txt new file mode 100644 index 00000000..fae7474a --- /dev/null +++ b/src/xdr/__tests__/rfc1832.txt @@ -0,0 +1,1347 @@ + + + + + + +Network Working Group R. Srinivasan +Request for Comments: 1832 Sun Microsystems +Category: Standards Track August 1995 + + + XDR: External Data Representation Standard + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +ABSTRACT + + This document describes the External Data Representation Standard + (XDR) protocol as it is currently deployed and accepted. + +TABLE OF CONTENTS + + 1. INTRODUCTION 2 + 2. BASIC BLOCK SIZE 2 + 3. XDR DATA TYPES 3 + 3.1 Integer 3 + 3.2 Unsigned Integer 4 + 3.3 Enumeration 4 + 3.4 Boolean 4 + 3.5 Hyper Integer and Unsigned Hyper Integer 4 + 3.6 Floating-point 5 + 3.7 Double-precision Floating-point 6 + 3.8 Quadruple-precision Floating-point 7 + 3.9 Fixed-length Opaque Data 8 + 3.10 Variable-length Opaque Data 8 + 3.11 String 9 + 3.12 Fixed-length Array 10 + 3.13 Variable-length Array 10 + 3.14 Structure 11 + 3.15 Discriminated Union 11 + 3.16 Void 12 + 3.17 Constant 12 + 3.18 Typedef 13 + 3.19 Optional-data 14 + 3.20 Areas for Future Enhancement 15 + 4. DISCUSSION 15 + 5. THE XDR LANGUAGE SPECIFICATION 17 + 5.1 Notational Conventions 17 + + + +Srinivasan Standards Track [Page 1] + +RFC 1832 XDR: External Data Representation Standard August 1995 + + + 5.2 Lexical Notes 17 + 5.3 Syntax Information 18 + 5.4 Syntax Notes 19 + 6. AN EXAMPLE OF AN XDR DATA DESCRIPTION 20 + 7. TRADEMARKS AND OWNERS 21 + APPENDIX A: ANSI/IEEE Standard 754-1985 22 + APPENDIX B: REFERENCES 24 + Security Considerations 24 + Author's Address 24 + +1. INTRODUCTION + + XDR is a standard for the description and encoding of data. It is + useful for transferring data between different computer + architectures, and has been used to communicate data between such + diverse machines as the SUN WORKSTATION*, VAX*, IBM-PC*, and Cray*. + XDR fits into the ISO presentation layer, and is roughly analogous in + purpose to X.409, ISO Abstract Syntax Notation. The major difference + between these two is that XDR uses implicit typing, while X.409 uses + explicit typing. + + XDR uses a language to describe data formats. The language can only + be used only to describe data; it is not a programming language. + This language allows one to describe intricate data formats in a + concise manner. The alternative of using graphical representations + (itself an informal language) quickly becomes incomprehensible when + faced with complexity. The XDR language itself is similar to the C + language [1], just as Courier [4] is similar to Mesa. Protocols such + as ONC RPC (Remote Procedure Call) and the NFS* (Network File System) + use XDR to describe the format of their data. + + The XDR standard makes the following assumption: that bytes (or + octets) are portable, where a byte is defined to be 8 bits of data. + A given hardware device should encode the bytes onto the various + media in such a way that other hardware devices may decode the bytes + without loss of meaning. For example, the Ethernet* standard + suggests that bytes be encoded in "little-endian" style [2], or least + significant bit first. + +2. BASIC BLOCK SIZE + + The representation of all items requires a multiple of four bytes (or + 32 bits) of data. The bytes are numbered 0 through n-1. The bytes + are read or written to some byte stream such that byte m always + precedes byte m+1. If the n bytes needed to contain the data are not + a multiple of four, then the n bytes are followed by enough (0 to 3) + residual zero bytes, r, to make the total byte count a multiple of 4. + + + + +Srinivasan Standards Track [Page 2] + +RFC 1832 XDR: External Data Representation Standard August 1995 + + + We include the familiar graphic box notation for illustration and + comparison. In most illustrations, each box (delimited by a plus + sign at the 4 corners and vertical bars and dashes) depicts a byte. + Ellipses (...) between boxes show zero or more additional bytes where + required. + + +--------+--------+...+--------+--------+...+--------+ + | byte 0 | byte 1 |...|byte n-1| 0 |...| 0 | BLOCK + +--------+--------+...+--------+--------+...+--------+ + |<-----------n bytes---------->|<------r bytes------>| + |<-----------n+r (where (n+r) mod 4 = 0)>----------->| + +3. XDR DATA TYPES + + Each of the sections that follow describes a data type defined in the + XDR standard, shows how it is declared in the language, and includes + a graphic illustration of its encoding. + + For each data type in the language we show a general paradigm + declaration. Note that angle brackets (< and >) denote + variablelength sequences of data and square brackets ([ and ]) denote + fixed-length sequences of data. "n", "m" and "r" denote integers. + For the full language specification and more formal definitions of + terms such as "identifier" and "declaration", refer to section 5: + "The XDR Language Specification". + + For some data types, more specific examples are included. A more + extensive example of a data description is in section 6: "An Example + of an XDR Data Description". + +3.1 Integer + + An XDR signed integer is a 32-bit datum that encodes an integer in + the range [-2147483648,2147483647]. The integer is represented in + two's complement notation. The most and least significant bytes are + 0 and 3, respectively. Integers are declared as follows: + + int identifier; + + (MSB) (LSB) + +-------+-------+-------+-------+ + |byte 0 |byte 1 |byte 2 |byte 3 | INTEGER + +-------+-------+-------+-------+ + <------------32 bits------------> + + + + + + + +Srinivasan Standards Track [Page 3] + +RFC 1832 XDR: External Data Representation Standard August 1995 + + +3.2. Unsigned Integer + + An XDR unsigned integer is a 32-bit datum that encodes a nonnegative + integer in the range [0,4294967295]. It is represented by an + unsigned binary number whose most and least significant bytes are 0 + and 3, respectively. An unsigned integer is declared as follows: + + unsigned int identifier; + + (MSB) (LSB) + +-------+-------+-------+-------+ + |byte 0 |byte 1 |byte 2 |byte 3 | UNSIGNED INTEGER + +-------+-------+-------+-------+ + <------------32 bits------------> + +3.3 Enumeration + + Enumerations have the same representation as signed integers. + Enumerations are handy for describing subsets of the integers. + Enumerated data is declared as follows: + + enum { name-identifier = constant, ... } identifier; + + For example, the three colors red, yellow, and blue could be + described by an enumerated type: + + enum { RED = 2, YELLOW = 3, BLUE = 5 } colors; + + It is an error to encode as an enum any other integer than those that + have been given assignments in the enum declaration. + +3.4 Boolean + + Booleans are important enough and occur frequently enough to warrant + their own explicit type in the standard. Booleans are declared as + follows: + + bool identifier; + + This is equivalent to: + + enum { FALSE = 0, TRUE = 1 } identifier; + +3.5 Hyper Integer and Unsigned Hyper Integer + + The standard also defines 64-bit (8-byte) numbers called hyper + integer and unsigned hyper integer. Their representations are the + obvious extensions of integer and unsigned integer defined above. + + + +Srinivasan Standards Track [Page 4] + +RFC 1832 XDR: External Data Representation Standard August 1995 + + + They are represented in two's complement notation. The most and + least significant bytes are 0 and 7, respectively. Their + declarations: + + hyper identifier; unsigned hyper identifier; + + (MSB) (LSB) + +-------+-------+-------+-------+-------+-------+-------+-------+ + |byte 0 |byte 1 |byte 2 |byte 3 |byte 4 |byte 5 |byte 6 |byte 7 | + +-------+-------+-------+-------+-------+-------+-------+-------+ + <----------------------------64 bits----------------------------> + HYPER INTEGER + UNSIGNED HYPER INTEGER + +3.6 Floating-point + + The standard defines the floating-point data type "float" (32 bits or + 4 bytes). The encoding used is the IEEE standard for normalized + single-precision floating-point numbers [3]. The following three + fields describe the single-precision floating-point number: + + S: The sign of the number. Values 0 and 1 represent positive and + negative, respectively. One bit. + + E: The exponent of the number, base 2. 8 bits are devoted to this + field. The exponent is biased by 127. + + F: The fractional part of the number's mantissa, base 2. 23 bits + are devoted to this field. + + Therefore, the floating-point number is described by: + + (-1)**S * 2**(E-Bias) * 1.F + + It is declared as follows: + + float identifier; + + +-------+-------+-------+-------+ + |byte 0 |byte 1 |byte 2 |byte 3 | SINGLE-PRECISION + S| E | F | FLOATING-POINT NUMBER + +-------+-------+-------+-------+ + 1|<- 8 ->|<-------23 bits------>| + <------------32 bits------------> + + Just as the most and least significant bytes of a number are 0 and 3, + the most and least significant bits of a single-precision floating- + point number are 0 and 31. The beginning bit (and most significant + + + +Srinivasan Standards Track [Page 5] + +RFC 1832 XDR: External Data Representation Standard August 1995 + + + bit) offsets of S, E, and F are 0, 1, and 9, respectively. Note that + these numbers refer to the mathematical positions of the bits, and + NOT to their actual physical locations (which vary from medium to + medium). + + The IEEE specifications should be consulted concerning the encoding + for signed zero, signed infinity (overflow), and denormalized numbers + (underflow) [3]. According to IEEE specifications, the "NaN" (not a + number) is system dependent and should not be interpreted within XDR + as anything other than "NaN". + +3.7 Double-precision Floating-point + + The standard defines the encoding for the double-precision floating- + point data type "double" (64 bits or 8 bytes). The encoding used is + the IEEE standard for normalized double-precision floating-point + numbers [3]. The standard encodes the following three fields, which + describe the double-precision floating-point number: + + S: The sign of the number. Values 0 and 1 represent positive and + negative, respectively. One bit. + + E: The exponent of the number, base 2. 11 bits are devoted to + this field. The exponent is biased by 1023. + + F: The fractional part of the number's mantissa, base 2. 52 bits + are devoted to this field. + + Therefore, the floating-point number is described by: + + (-1)**S * 2**(E-Bias) * 1.F + + It is declared as follows: + + double identifier; + + +------+------+------+------+------+------+------+------+ + |byte 0|byte 1|byte 2|byte 3|byte 4|byte 5|byte 6|byte 7| + S| E | F | + +------+------+------+------+------+------+------+------+ + 1|<--11-->|<-----------------52 bits------------------->| + <-----------------------64 bits-------------------------> + DOUBLE-PRECISION FLOATING-POINT + + Just as the most and least significant bytes of a number are 0 and 3, + the most and least significant bits of a double-precision floating- + point number are 0 and 63. The beginning bit (and most significant + bit) offsets of S, E , and F are 0, 1, and 12, respectively. Note + + + +Srinivasan Standards Track [Page 6] + +RFC 1832 XDR: External Data Representation Standard August 1995 + + + that these numbers refer to the mathematical positions of the bits, + and NOT to their actual physical locations (which vary from medium to + medium). + + The IEEE specifications should be consulted concerning the encoding + for signed zero, signed infinity (overflow), and denormalized numbers + (underflow) [3]. According to IEEE specifications, the "NaN" (not a + number) is system dependent and should not be interpreted within XDR + as anything other than "NaN". + +3.8 Quadruple-precision Floating-point + + The standard defines the encoding for the quadruple-precision + floating-point data type "quadruple" (128 bits or 16 bytes). The + encoding used is designed to be a simple analog of of the encoding + used for single and double-precision floating-point numbers using one + form of IEEE double extended precision. The standard encodes the + following three fields, which describe the quadruple-precision + floating-point number: + + S: The sign of the number. Values 0 and 1 represent positive and + negative, respectively. One bit. + + E: The exponent of the number, base 2. 15 bits are devoted to + this field. The exponent is biased by 16383. + + F: The fractional part of the number's mantissa, base 2. 112 bits + are devoted to this field. + + Therefore, the floating-point number is described by: + + (-1)**S * 2**(E-Bias) * 1.F + + It is declared as follows: + + quadruple identifier; + + +------+------+------+------+------+------+-...--+------+ + |byte 0|byte 1|byte 2|byte 3|byte 4|byte 5| ... |byte15| + S| E | F | + +------+------+------+------+------+------+-...--+------+ + 1|<----15---->|<-------------112 bits------------------>| + <-----------------------128 bits------------------------> + QUADRUPLE-PRECISION FLOATING-POINT + + Just as the most and least significant bytes of a number are 0 and 3, + the most and least significant bits of a quadruple-precision + floating-point number are 0 and 127. The beginning bit (and most + + + +Srinivasan Standards Track [Page 7] + +RFC 1832 XDR: External Data Representation Standard August 1995 + + + significant bit) offsets of S, E , and F are 0, 1, and 16, + respectively. Note that these numbers refer to the mathematical + positions of the bits, and NOT to their actual physical locations + (which vary from medium to medium). + + The encoding for signed zero, signed infinity (overflow), and + denormalized numbers are analogs of the corresponding encodings for + single and double-precision floating-point numbers [5], [6]. The + "NaN" encoding as it applies to quadruple-precision floating-point + numbers is system dependent and should not be interpreted within XDR + as anything other than "NaN". + +3.9 Fixed-length Opaque Data + + At times, fixed-length uninterpreted data needs to be passed among + machines. This data is called "opaque" and is declared as follows: + + opaque identifier[n]; + + where the constant n is the (static) number of bytes necessary to + contain the opaque data. If n is not a multiple of four, then the n + bytes are followed by enough (0 to 3) residual zero bytes, r, to make + the total byte count of the opaque object a multiple of four. + + 0 1 ... + +--------+--------+...+--------+--------+...+--------+ + | byte 0 | byte 1 |...|byte n-1| 0 |...| 0 | + +--------+--------+...+--------+--------+...+--------+ + |<-----------n bytes---------->|<------r bytes------>| + |<-----------n+r (where (n+r) mod 4 = 0)------------>| + FIXED-LENGTH OPAQUE + +3.10 Variable-length Opaque Data + + The standard also provides for variable-length (counted) opaque data, + defined as a sequence of n (numbered 0 through n-1) arbitrary bytes + to be the number n encoded as an unsigned integer (as described + below), and followed by the n bytes of the sequence. + + + + + + + + + + + + + +Srinivasan Standards Track [Page 8] + +RFC 1832 XDR: External Data Representation Standard August 1995 + + + Byte m of the sequence always precedes byte m+1 of the sequence, and + byte 0 of the sequence always follows the sequence's length (count). + If n is not a multiple of four, then the n bytes are followed by + enough (0 to 3) residual zero bytes, r, to make the total byte count + a multiple of four. Variable-length opaque data is declared in the + following way: + + opaque identifier; + or + opaque identifier<>; + + The constant m denotes an upper bound of the number of bytes that the + sequence may contain. If m is not specified, as in the second + declaration, it is assumed to be (2**32) - 1, the maximum length. + The constant m would normally be found in a protocol specification. + For example, a filing protocol may state that the maximum data + transfer size is 8192 bytes, as follows: + + opaque filedata<8192>; + + 0 1 2 3 4 5 ... + +-----+-----+-----+-----+-----+-----+...+-----+-----+...+-----+ + | length n |byte0|byte1|...| n-1 | 0 |...| 0 | + +-----+-----+-----+-----+-----+-----+...+-----+-----+...+-----+ + |<-------4 bytes------->|<------n bytes------>|<---r bytes--->| + |<----n+r (where (n+r) mod 4 = 0)---->| + VARIABLE-LENGTH OPAQUE + + It is an error to encode a length greater than the maximum described + in the specification. + +3.11 String + + The standard defines a string of n (numbered 0 through n-1) ASCII + bytes to be the number n encoded as an unsigned integer (as described + above), and followed by the n bytes of the string. Byte m of the + string always precedes byte m+1 of the string, and byte 0 of the + string always follows the string's length. If n is not a multiple of + four, then the n bytes are followed by enough (0 to 3) residual zero + bytes, r, to make the total byte count a multiple of four. Counted + byte strings are declared as follows: + + string object; + or + string object<>; + + The constant m denotes an upper bound of the number of bytes that a + string may contain. If m is not specified, as in the second + + + +Srinivasan Standards Track [Page 9] + +RFC 1832 XDR: External Data Representation Standard August 1995 + + + declaration, it is assumed to be (2**32) - 1, the maximum length. + The constant m would normally be found in a protocol specification. + For example, a filing protocol may state that a file name can be no + longer than 255 bytes, as follows: + + string filename<255>; + + 0 1 2 3 4 5 ... + +-----+-----+-----+-----+-----+-----+...+-----+-----+...+-----+ + | length n |byte0|byte1|...| n-1 | 0 |...| 0 | + +-----+-----+-----+-----+-----+-----+...+-----+-----+...+-----+ + |<-------4 bytes------->|<------n bytes------>|<---r bytes--->| + |<----n+r (where (n+r) mod 4 = 0)---->| + STRING + + It is an error to encode a length greater than the maximum described + in the specification. + +3.12 Fixed-length Array + + Declarations for fixed-length arrays of homogeneous elements are in + the following form: + + type-name identifier[n]; + + Fixed-length arrays of elements numbered 0 through n-1 are encoded by + individually encoding the elements of the array in their natural + order, 0 through n-1. Each element's size is a multiple of four + bytes. Though all elements are of the same type, the elements may + have different sizes. For example, in a fixed-length array of + strings, all elements are of type "string", yet each element will + vary in its length. + + +---+---+---+---+---+---+---+---+...+---+---+---+---+ + | element 0 | element 1 |...| element n-1 | + +---+---+---+---+---+---+---+---+...+---+---+---+---+ + |<--------------------n elements------------------->| + + FIXED-LENGTH ARRAY + +3.13 Variable-length Array + +Counted arrays provide the ability to encode variable-length arrays of +homogeneous elements. The array is encoded as the element count n (an +unsigned integer) followed by the encoding of each of the array's +elements, starting with element 0 and progressing through element n- 1. +The declaration for variable-length arrays follows this form: + + + + +Srinivasan Standards Track [Page 10] + +RFC 1832 XDR: External Data Representation Standard August 1995 + + + type-name identifier; + or + type-name identifier<>; + + The constant m specifies the maximum acceptable element count of an + array; if m is not specified, as in the second declaration, it is + assumed to be (2**32) - 1. + + 0 1 2 3 + +--+--+--+--+--+--+--+--+--+--+--+--+...+--+--+--+--+ + | n | element 0 | element 1 |...|element n-1| + +--+--+--+--+--+--+--+--+--+--+--+--+...+--+--+--+--+ + |<-4 bytes->|<--------------n elements------------->| + COUNTED ARRAY + + It is an error to encode a value of n that is greater than the + maximum described in the specification. + +3.14 Structure + + Structures are declared as follows: + + struct { + component-declaration-A; + component-declaration-B; + ... + } identifier; + + The components of the structure are encoded in the order of their + declaration in the structure. Each component's size is a multiple of + four bytes, though the components may be different sizes. + + +-------------+-------------+... + | component A | component B |... STRUCTURE + +-------------+-------------+... + +3.15 Discriminated Union + + A discriminated union is a type composed of a discriminant followed + by a type selected from a set of prearranged types according to the + value of the discriminant. The type of discriminant is either "int", + "unsigned int", or an enumerated type, such as "bool". The component + types are called "arms" of the union, and are preceded by the value + of the discriminant which implies their encoding. Discriminated + unions are declared as follows: + + union switch (discriminant-declaration) { + case discriminant-value-A: + + + +Srinivasan Standards Track [Page 11] + +RFC 1832 XDR: External Data Representation Standard August 1995 + + + arm-declaration-A; + case discriminant-value-B: + arm-declaration-B; + ... + default: default-declaration; + } identifier; + + Each "case" keyword is followed by a legal value of the discriminant. + The default arm is optional. If it is not specified, then a valid + encoding of the union cannot take on unspecified discriminant values. + The size of the implied arm is always a multiple of four bytes. + + The discriminated union is encoded as its discriminant followed by + the encoding of the implied arm. + + 0 1 2 3 + +---+---+---+---+---+---+---+---+ + | discriminant | implied arm | DISCRIMINATED UNION + +---+---+---+---+---+---+---+---+ + |<---4 bytes--->| + +3.16 Void + + An XDR void is a 0-byte quantity. Voids are useful for describing + operations that take no data as input or no data as output. They are + also useful in unions, where some arms may contain data and others do + not. The declaration is simply as follows: + + void; + + Voids are illustrated as follows: + + ++ + || VOID + ++ + --><-- 0 bytes + +3.17 Constant + + The data declaration for a constant follows this form: + + const name-identifier = n; + + "const" is used to define a symbolic name for a constant; it does not + declare any data. The symbolic constant may be used anywhere a + regular constant may be used. For example, the following defines a + symbolic constant DOZEN, equal to 12. + + + + +Srinivasan Standards Track [Page 12] + +RFC 1832 XDR: External Data Representation Standard August 1995 + + + const DOZEN = 12; + +3.18 Typedef + + "typedef" does not declare any data either, but serves to define new + identifiers for declaring data. The syntax is: + + typedef declaration; + + The new type name is actually the variable name in the declaration + part of the typedef. For example, the following defines a new type + called "eggbox" using an existing type called "egg": + + typedef egg eggbox[DOZEN]; + + Variables declared using the new type name have the same type as the + new type name would have in the typedef, if it was considered a + variable. For example, the following two declarations are equivalent + in declaring the variable "fresheggs": + + eggbox fresheggs; egg fresheggs[DOZEN]; + + When a typedef involves a struct, enum, or union definition, there is + another (preferred) syntax that may be used to define the same type. + In general, a typedef of the following form: + + typedef <> identifier; + + may be converted to the alternative form by removing the "typedef" + part and placing the identifier after the "struct", "union", or + "enum" keyword, instead of at the end. For example, here are the two + ways to define the type "bool": + + typedef enum { /* using typedef */ + FALSE = 0, + TRUE = 1 + } bool; + + enum bool { /* preferred alternative */ + FALSE = 0, + TRUE = 1 + }; + + The reason this syntax is preferred is one does not have to wait + until the end of a declaration to figure out the name of the new + type. + + + + + +Srinivasan Standards Track [Page 13] + +RFC 1832 XDR: External Data Representation Standard August 1995 + + +3.19 Optional-data + + Optional-data is one kind of union that occurs so frequently that we + give it a special syntax of its own for declaring it. It is declared + as follows: + + type-name *identifier; + + This is equivalent to the following union: + + union switch (bool opted) { + case TRUE: + type-name element; + case FALSE: + void; + } identifier; + + It is also equivalent to the following variable-length array + declaration, since the boolean "opted" can be interpreted as the + length of the array: + + type-name identifier<1>; + + Optional-data is not so interesting in itself, but it is very useful + for describing recursive data-structures such as linked-lists and + trees. For example, the following defines a type "stringlist" that + encodes lists of arbitrary length strings: + + struct *stringlist { + string item<>; + stringlist next; + }; + + It could have been equivalently declared as the following union: + + union stringlist switch (bool opted) { + case TRUE: + struct { + string item<>; + stringlist next; + } element; + case FALSE: + void; + }; + + or as a variable-length array: + + struct stringlist<1> { + + + +Srinivasan Standards Track [Page 14] + +RFC 1832 XDR: External Data Representation Standard August 1995 + + + string item<>; + stringlist next; + }; + + Both of these declarations obscure the intention of the stringlist + type, so the optional-data declaration is preferred over both of + them. The optional-data type also has a close correlation to how + recursive data structures are represented in high-level languages + such as Pascal or C by use of pointers. In fact, the syntax is the + same as that of the C language for pointers. + +3.20 Areas for Future Enhancement + + The XDR standard lacks representations for bit fields and bitmaps, + since the standard is based on bytes. Also missing are packed (or + binary-coded) decimals. + + The intent of the XDR standard was not to describe every kind of data + that people have ever sent or will ever want to send from machine to + machine. Rather, it only describes the most commonly used data-types + of high-level languages such as Pascal or C so that applications + written in these languages will be able to communicate easily over + some medium. + + One could imagine extensions to XDR that would let it describe almost + any existing protocol, such as TCP. The minimum necessary for this + are support for different block sizes and byte-orders. The XDR + discussed here could then be considered the 4-byte big-endian member + of a larger XDR family. + +4. DISCUSSION + + (1) Why use a language for describing data? What's wrong with + diagrams? + + There are many advantages in using a data-description language such + as XDR versus using diagrams. Languages are more formal than + diagrams and lead to less ambiguous descriptions of data. Languages + are also easier to understand and allow one to think of other issues + instead of the low-level details of bit-encoding. Also, there is a + close analogy between the types of XDR and a high-level language such + as C or Pascal. This makes the implementation of XDR encoding and + decoding modules an easier task. Finally, the language specification + itself is an ASCII string that can be passed from machine to machine + to perform on-the-fly data interpretation. + + + + + + +Srinivasan Standards Track [Page 15] + +RFC 1832 XDR: External Data Representation Standard August 1995 + + + (2) Why is there only one byte-order for an XDR unit? + + Supporting two byte-orderings requires a higher level protocol for + determining in which byte-order the data is encoded. Since XDR is + not a protocol, this can't be done. The advantage of this, though, + is that data in XDR format can be written to a magnetic tape, for + example, and any machine will be able to interpret it, since no + higher level protocol is necessary for determining the byte-order. + + (3) Why is the XDR byte-order big-endian instead of little-endian? + Isn't this unfair to little-endian machines such as the VAX(r), which + has to convert from one form to the other? + + Yes, it is unfair, but having only one byte-order means you have to + be unfair to somebody. Many architectures, such as the Motorola + 68000* and IBM 370*, support the big-endian byte-order. + + (4) Why is the XDR unit four bytes wide? + + There is a tradeoff in choosing the XDR unit size. Choosing a small + size such as two makes the encoded data small, but causes alignment + problems for machines that aren't aligned on these boundaries. A + large size such as eight means the data will be aligned on virtually + every machine, but causes the encoded data to grow too big. We chose + four as a compromise. Four is big enough to support most + architectures efficiently, except for rare machines such as the + eight-byte aligned Cray*. Four is also small enough to keep the + encoded data restricted to a reasonable size. + + (5) Why must variable-length data be padded with zeros? + + It is desirable that the same data encode into the same thing on all + machines, so that encoded data can be meaningfully compared or + checksummed. Forcing the padded bytes to be zero ensures this. + + (6) Why is there no explicit data-typing? + + Data-typing has a relatively high cost for what small advantages it + may have. One cost is the expansion of data due to the inserted type + fields. Another is the added cost of interpreting these type fields + and acting accordingly. And most protocols already know what type + they expect, so data-typing supplies only redundant information. + However, one can still get the benefits of data-typing using XDR. One + way is to encode two things: first a string which is the XDR data + description of the encoded data, and then the encoded data itself. + Another way is to assign a value to all the types in XDR, and then + define a universal type which takes this value as its discriminant + and for each value, describes the corresponding data type. + + + +Srinivasan Standards Track [Page 16] + +RFC 1832 XDR: External Data Representation Standard August 1995 + + +5. THE XDR LANGUAGE SPECIFICATION + +5.1 Notational Conventions + + This specification uses an extended Back-Naur Form notation for + describing the XDR language. Here is a brief description of the + notation: + + (1) The characters '|', '(', ')', '[', ']', '"', and '*' are special. + (2) Terminal symbols are strings of any characters surrounded by + double quotes. (3) Non-terminal symbols are strings of non-special + characters. (4) Alternative items are separated by a vertical bar + ("|"). (5) Optional items are enclosed in brackets. (6) Items are + grouped together by enclosing them in parentheses. (7) A '*' + following an item means 0 or more occurrences of that item. + + For example, consider the following pattern: + + "a " "very" (", " "very")* [" cold " "and "] " rainy " + ("day" | "night") + + An infinite number of strings match this pattern. A few of them are: + + "a very rainy day" + "a very, very rainy day" + "a very cold and rainy day" + "a very, very, very cold and rainy night" + +5.2 Lexical Notes + + (1) Comments begin with '/*' and terminate with '*/'. (2) White + space serves to separate items and is otherwise ignored. (3) An + identifier is a letter followed by an optional sequence of letters, + digits or underbar ('_'). The case of identifiers is not ignored. + (4) A constant is a sequence of one or more decimal digits, + optionally preceded by a minus-sign ('-'). + + + + + + + + + + + + + + + +Srinivasan Standards Track [Page 17] + +RFC 1832 XDR: External Data Representation Standard August 1995 + + +5.3 Syntax Information + + declaration: + type-specifier identifier + | type-specifier identifier "[" value "]" + | type-specifier identifier "<" [ value ] ">" + | "opaque" identifier "[" value "]" + | "opaque" identifier "<" [ value ] ">" + | "string" identifier "<" [ value ] ">" + | type-specifier "*" identifier + | "void" + + value: + constant + | identifier + + type-specifier: + [ "unsigned" ] "int" + | [ "unsigned" ] "hyper" + | "float" + | "double" + | "quadruple" + | "bool" + | enum-type-spec + | struct-type-spec + | union-type-spec + | identifier + + enum-type-spec: + "enum" enum-body + + enum-body: + "{" + ( identifier "=" value ) + ( "," identifier "=" value )* + "}" + + struct-type-spec: + "struct" struct-body + + struct-body: + "{" + ( declaration ";" ) + ( declaration ";" )* + "}" + + union-type-spec: + "union" union-body + + + +Srinivasan Standards Track [Page 18] + +RFC 1832 XDR: External Data Representation Standard August 1995 + + + union-body: + "switch" "(" declaration ")" "{" + ( "case" value ":" declaration ";" ) + ( "case" value ":" declaration ";" )* + [ "default" ":" declaration ";" ] + "}" + + constant-def: + "const" identifier "=" constant ";" + + type-def: + "typedef" declaration ";" + | "enum" identifier enum-body ";" + | "struct" identifier struct-body ";" + | "union" identifier union-body ";" + + definition: + type-def + | constant-def + + specification: + definition * + +5.4 Syntax Notes + + (1) The following are keywords and cannot be used as identifiers: + "bool", "case", "const", "default", "double", "quadruple", "enum", + "float", "hyper", "opaque", "string", "struct", "switch", "typedef", + "union", "unsigned" and "void". + + (2) Only unsigned constants may be used as size specifications for + arrays. If an identifier is used, it must have been declared + previously as an unsigned constant in a "const" definition. + + (3) Constant and type identifiers within the scope of a specification + are in the same name space and must be declared uniquely within this + scope. + + (4) Similarly, variable names must be unique within the scope of + struct and union declarations. Nested struct and union declarations + create new scopes. + + (5) The discriminant of a union must be of a type that evaluates to + an integer. That is, "int", "unsigned int", "bool", an enumerated + type or any typedefed type that evaluates to one of these is legal. + Also, the case values must be one of the legal values of the + discriminant. Finally, a case value may not be specified more than + once within the scope of a union declaration. + + + +Srinivasan Standards Track [Page 19] + +RFC 1832 XDR: External Data Representation Standard August 1995 + + +6. AN EXAMPLE OF AN XDR DATA DESCRIPTION + + Here is a short XDR data description of a thing called a "file", + which might be used to transfer files from one machine to another. + + const MAXUSERNAME = 32; /* max length of a user name */ + const MAXFILELEN = 65535; /* max length of a file */ + const MAXNAMELEN = 255; /* max length of a file name */ + + /* + * Types of files: + */ + enum filekind { + TEXT = 0, /* ascii data */ + DATA = 1, /* raw data */ + EXEC = 2 /* executable */ + }; + + /* + * File information, per kind of file: + */ + union filetype switch (filekind kind) { + case TEXT: + void; /* no extra information */ + case DATA: + string creator; /* data creator */ + case EXEC: + string interpretor; /* program interpretor */ + }; + + /* + * A complete file: + */ + struct file { + string filename; /* name of file */ + filetype type; /* info about file */ + string owner; /* owner of file */ + opaque data; /* file data */ + }; + + + + + + + + + + + + +Srinivasan Standards Track [Page 20] + +RFC 1832 XDR: External Data Representation Standard August 1995 + + + Suppose now that there is a user named "john" who wants to store his + lisp program "sillyprog" that contains just the data "(quit)". His + file would be encoded as follows: + + OFFSET HEX BYTES ASCII COMMENTS + ------ --------- ----- -------- + 0 00 00 00 09 .... -- length of filename = 9 + 4 73 69 6c 6c sill -- filename characters + 8 79 70 72 6f ypro -- ... and more characters ... + 12 67 00 00 00 g... -- ... and 3 zero-bytes of fill + 16 00 00 00 02 .... -- filekind is EXEC = 2 + 20 00 00 00 04 .... -- length of interpretor = 4 + 24 6c 69 73 70 lisp -- interpretor characters + 28 00 00 00 04 .... -- length of owner = 4 + 32 6a 6f 68 6e john -- owner characters + 36 00 00 00 06 .... -- length of file data = 6 + 40 28 71 75 69 (qui -- file data bytes ... + 44 74 29 00 00 t).. -- ... and 2 zero-bytes of fill + +7. TRADEMARKS AND OWNERS + + SUN WORKSTATION Sun Microsystems, Inc. + VAX Digital Equipment Corporation + IBM-PC International Business Machines Corporation + Cray Cray Research + NFS Sun Microsystems, Inc. + Ethernet Xerox Corporation. + Motorola 68000 Motorola, Inc. + IBM 370 International Business Machines Corporation + + + + + + + + + + + + + + + + + + + + + + +Srinivasan Standards Track [Page 21] + +RFC 1832 XDR: External Data Representation Standard August 1995 + + +APPENDIX A: ANSI/IEEE Standard 754-1985 + + The definition of NaNs, signed zero and infinity, and denormalized + numbers from [3] is reproduced here for convenience. The definitions + for quadruple-precision floating point numbers are analogs of those + for single and double-precision floating point numbers, and are + defined in [3]. + + In the following, 'S' stands for the sign bit, 'E' for the exponent, + and 'F' for the fractional part. The symbol 'u' stands for an + undefined bit (0 or 1). + + For single-precision floating point numbers: + + Type S (1 bit) E (8 bits) F (23 bits) + ---- --------- ---------- ----------- + signalling NaN u 255 (max) .0uuuuu---u + (with at least + one 1 bit) + quiet NaN u 255 (max) .1uuuuu---u + + negative infinity 1 255 (max) .000000---0 + + positive infinity 0 255 (max) .000000---0 + + negative zero 1 0 .000000---0 + + positive zero 0 0 .000000---0 + +For double-precision floating point numbers: + + Type S (1 bit) E (11 bits) F (52 bits) + ---- --------- ----------- ----------- + signalling NaN u 2047 (max) .0uuuuu---u + (with at least + one 1 bit) + quiet NaN u 2047 (max) .1uuuuu---u + + negative infinity 1 2047 (max) .000000---0 + + positive infinity 0 2047 (max) .000000---0 + + negative zero 1 0 .000000---0 + + positive zero 0 0 .000000---0 + + + + + + +Srinivasan Standards Track [Page 22] + +RFC 1832 XDR: External Data Representation Standard August 1995 + + +For quadruple-precision floating point numbers: + + Type S (1 bit) E (15 bits) F (112 bits) + ---- --------- ----------- ------------ + signalling NaN u 32767 (max) .0uuuuu---u + (with at least + one 1 bit) + quiet NaN u 32767 (max) .1uuuuu---u + + negative infinity 1 32767 (max) .000000---0 + + positive infinity 0 32767 (max) .000000---0 + + negative zero 1 0 .000000---0 + + positive zero 0 0 .000000---0 + +Subnormal numbers are represented as follows: + + Precision Exponent Value + --------- -------- ----- + Single 0 (-1)**S * 2**(-126) * 0.F + + Double 0 (-1)**S * 2**(-1022) * 0.F + + Quadruple 0 (-1)**S * 2**(-16382) * 0.F + + + + + + + + + + + + + + + + + + + + + + + + + +Srinivasan Standards Track [Page 23] + +RFC 1832 XDR: External Data Representation Standard August 1995 + + +APPENDIX B: REFERENCES + + [1] Brian W. Kernighan & Dennis M. Ritchie, "The C Programming + Language", Bell Laboratories, Murray Hill, New Jersey, 1978. + + [2] Danny Cohen, "On Holy Wars and a Plea for Peace", IEEE Computer, + October 1981. + + [3] "IEEE Standard for Binary Floating-Point Arithmetic", ANSI/IEEE + Standard 754-1985, Institute of Electrical and Electronics + Engineers, August 1985. + + [4] "Courier: The Remote Procedure Call Protocol", XEROX + Corporation, XSIS 038112, December 1981. + + [5] "The SPARC Architecture Manual: Version 8", Prentice Hall, + ISBN 0-13-825001-4. + + [6] "HP Precision Architecture Handbook", June 1987, 5954-9906. + + [7] Srinivasan, R., "Remote Procedure Call Protocol Version 2", + RFC 1831, Sun Microsystems, Inc., August 1995. + +Security Considerations + + Security issues are not discussed in this memo. + +Author's Address + + Raj Srinivasan + Sun Microsystems, Inc. + ONC Technologies + 2550 Garcia Avenue + M/S MTV-5-40 + Mountain View, CA 94043 + USA + + Phone: 415-336-2478 + Fax: 415-336-6015 + EMail: raj@eng.sun.com + + + + + + + + + + + +Srinivasan Standards Track [Page 24] + diff --git a/src/xdr/__tests__/rfc4506.txt b/src/xdr/__tests__/rfc4506.txt new file mode 100644 index 00000000..9bd6a890 --- /dev/null +++ b/src/xdr/__tests__/rfc4506.txt @@ -0,0 +1,1515 @@ + + + + + + +Network Working Group M. Eisler, Ed. +Request for Comments: 4506 Network Appliance, Inc. +STD: 67 May 2006 +Obsoletes: 1832 +Category: Standards Track + + + XDR: External Data Representation Standard + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2006). + +Abstract + + This document describes the External Data Representation Standard + (XDR) protocol as it is currently deployed and accepted. This + document obsoletes RFC 1832. + + + + + + + + + + + + + + + + + + + + + + + + + +Eisler Standards Track [Page 1] + +RFC 4506 XDR: External Data Representation Standard May 2006 + + +Table of Contents + + 1. Introduction ....................................................3 + 2. Changes from RFC 1832 ...........................................3 + 3. Basic Block Size ................................................3 + 4. XDR Data Types ..................................................4 + 4.1. Integer ....................................................4 + 4.2. Unsigned Integer ...........................................4 + 4.3. Enumeration ................................................5 + 4.4. Boolean ....................................................5 + 4.5. Hyper Integer and Unsigned Hyper Integer ...................5 + 4.6. Floating-Point .............................................6 + 4.7. Double-Precision Floating-Point ............................7 + 4.8. Quadruple-Precision Floating-Point .........................8 + 4.9. Fixed-Length Opaque Data ...................................9 + 4.10. Variable-Length Opaque Data ...............................9 + 4.11. String ...................................................10 + 4.12. Fixed-Length Array .......................................11 + 4.13. Variable-Length Array ....................................11 + 4.14. Structure ................................................12 + 4.15. Discriminated Union ......................................12 + 4.16. Void .....................................................13 + 4.17. Constant .................................................13 + 4.18. Typedef ..................................................13 + 4.19. Optional-Data ............................................14 + 4.20. Areas for Future Enhancement .............................16 + 5. Discussion .....................................................16 + 6. The XDR Language Specification .................................17 + 6.1. Notational Conventions ....................................17 + 6.2. Lexical Notes .............................................18 + 6.3. Syntax Information ........................................18 + 6.4. Syntax Notes ..............................................20 + 7. An Example of an XDR Data Description ..........................21 + 8. Security Considerations ........................................22 + 9. IANA Considerations ............................................23 + 10. Trademarks and Owners .........................................23 + 11. ANSI/IEEE Standard 754-1985 ...................................24 + 12. Normative References ..........................................25 + 13. Informative References ........................................25 + 14. Acknowledgements ..............................................26 + + + + + + + + + + + +Eisler Standards Track [Page 2] + +RFC 4506 XDR: External Data Representation Standard May 2006 + + +1. Introduction + + XDR is a standard for the description and encoding of data. It is + useful for transferring data between different computer + architectures, and it has been used to communicate data between such + diverse machines as the SUN WORKSTATION*, VAX*, IBM-PC*, and Cray*. + XDR fits into the ISO presentation layer and is roughly analogous in + purpose to X.409, ISO Abstract Syntax Notation. The major difference + between these two is that XDR uses implicit typing, while X.409 uses + explicit typing. + + XDR uses a language to describe data formats. The language can be + used only to describe data; it is not a programming language. This + language allows one to describe intricate data formats in a concise + manner. The alternative of using graphical representations (itself + an informal language) quickly becomes incomprehensible when faced + with complexity. The XDR language itself is similar to the C + language [KERN], just as Courier [COUR] is similar to Mesa. + Protocols such as ONC RPC (Remote Procedure Call) and the NFS* + (Network File System) use XDR to describe the format of their data. + + The XDR standard makes the following assumption: that bytes (or + octets) are portable, where a byte is defined as 8 bits of data. A + given hardware device should encode the bytes onto the various media + in such a way that other hardware devices may decode the bytes + without loss of meaning. For example, the Ethernet* standard + suggests that bytes be encoded in "little-endian" style [COHE], or + least significant bit first. + +2. Changes from RFC 1832 + + This document makes no technical changes to RFC 1832 and is published + for the purposes of noting IANA considerations, augmenting security + considerations, and distinguishing normative from informative + references. + +3. Basic Block Size + + The representation of all items requires a multiple of four bytes (or + 32 bits) of data. The bytes are numbered 0 through n-1. The bytes + are read or written to some byte stream such that byte m always + precedes byte m+1. If the n bytes needed to contain the data are not + a multiple of four, then the n bytes are followed by enough (0 to 3) + residual zero bytes, r, to make the total byte count a multiple of 4. + + We include the familiar graphic box notation for illustration and + comparison. In most illustrations, each box (delimited by a plus + sign at the 4 corners and vertical bars and dashes) depicts a byte. + + + +Eisler Standards Track [Page 3] + +RFC 4506 XDR: External Data Representation Standard May 2006 + + + Ellipses (...) between boxes show zero or more additional bytes where + required. + + +--------+--------+...+--------+--------+...+--------+ + | byte 0 | byte 1 |...|byte n-1| 0 |...| 0 | BLOCK + +--------+--------+...+--------+--------+...+--------+ + |<-----------n bytes---------->|<------r bytes------>| + |<-----------n+r (where (n+r) mod 4 = 0)>----------->| + +4. XDR Data Types + + Each of the sections that follow describes a data type defined in the + XDR standard, shows how it is declared in the language, and includes + a graphic illustration of its encoding. + + For each data type in the language we show a general paradigm + declaration. Note that angle brackets (< and >) denote variable- + length sequences of data and that square brackets ([ and ]) denote + fixed-length sequences of data. "n", "m", and "r" denote integers. + For the full language specification and more formal definitions of + terms such as "identifier" and "declaration", refer to Section 6, + "The XDR Language Specification". + + For some data types, more specific examples are included. A more + extensive example of a data description is in Section 7, "An Example + of an XDR Data Description". + +4.1. Integer + + An XDR signed integer is a 32-bit datum that encodes an integer in + the range [-2147483648,2147483647]. The integer is represented in + two's complement notation. The most and least significant bytes are + 0 and 3, respectively. Integers are declared as follows: + + int identifier; + + (MSB) (LSB) + +-------+-------+-------+-------+ + |byte 0 |byte 1 |byte 2 |byte 3 | INTEGER + +-------+-------+-------+-------+ + <------------32 bits------------> + +4.2. Unsigned Integer + + An XDR unsigned integer is a 32-bit datum that encodes a non-negative + integer in the range [0,4294967295]. It is represented by an + unsigned binary number whose most and least significant bytes are 0 + and 3, respectively. An unsigned integer is declared as follows: + + + +Eisler Standards Track [Page 4] + +RFC 4506 XDR: External Data Representation Standard May 2006 + + + unsigned int identifier; + + (MSB) (LSB) + +-------+-------+-------+-------+ + |byte 0 |byte 1 |byte 2 |byte 3 | UNSIGNED INTEGER + +-------+-------+-------+-------+ + <------------32 bits------------> + +4.3. Enumeration + + Enumerations have the same representation as signed integers. + Enumerations are handy for describing subsets of the integers. + Enumerated data is declared as follows: + + enum { name-identifier = constant, ... } identifier; + + For example, the three colors red, yellow, and blue could be + described by an enumerated type: + + enum { RED = 2, YELLOW = 3, BLUE = 5 } colors; + + It is an error to encode as an enum any integer other than those that + have been given assignments in the enum declaration. + +4.4. Boolean + + Booleans are important enough and occur frequently enough to warrant + their own explicit type in the standard. Booleans are declared as + follows: + + bool identifier; + + This is equivalent to: + + enum { FALSE = 0, TRUE = 1 } identifier; + +4.5. Hyper Integer and Unsigned Hyper Integer + + The standard also defines 64-bit (8-byte) numbers called hyper + integers and unsigned hyper integers. Their representations are the + obvious extensions of integer and unsigned integer defined above. + They are represented in two's complement notation. The most and + least significant bytes are 0 and 7, respectively. Their + declarations: + + hyper identifier; unsigned hyper identifier; + + + + + +Eisler Standards Track [Page 5] + +RFC 4506 XDR: External Data Representation Standard May 2006 + + + (MSB) (LSB) + +-------+-------+-------+-------+-------+-------+-------+-------+ + |byte 0 |byte 1 |byte 2 |byte 3 |byte 4 |byte 5 |byte 6 |byte 7 | + +-------+-------+-------+-------+-------+-------+-------+-------+ + <----------------------------64 bits----------------------------> + HYPER INTEGER + UNSIGNED HYPER INTEGER + +4.6. Floating-Point + + The standard defines the floating-point data type "float" (32 bits or + 4 bytes). The encoding used is the IEEE standard for normalized + single-precision floating-point numbers [IEEE]. The following three + fields describe the single-precision floating-point number: + + S: The sign of the number. Values 0 and 1 represent positive and + negative, respectively. One bit. + + E: The exponent of the number, base 2. 8 bits are devoted to this + field. The exponent is biased by 127. + + F: The fractional part of the number's mantissa, base 2. 23 bits + are devoted to this field. + + Therefore, the floating-point number is described by: + + (-1)**S * 2**(E-Bias) * 1.F + + It is declared as follows: + + float identifier; + + +-------+-------+-------+-------+ + |byte 0 |byte 1 |byte 2 |byte 3 | SINGLE-PRECISION + S| E | F | FLOATING-POINT NUMBER + +-------+-------+-------+-------+ + 1|<- 8 ->|<-------23 bits------>| + <------------32 bits------------> + + Just as the most and least significant bytes of a number are 0 and 3, + the most and least significant bits of a single-precision floating- + point number are 0 and 31. The beginning bit (and most significant + bit) offsets of S, E, and F are 0, 1, and 9, respectively. Note that + these numbers refer to the mathematical positions of the bits, and + NOT to their actual physical locations (which vary from medium to + medium). + + + + + +Eisler Standards Track [Page 6] + +RFC 4506 XDR: External Data Representation Standard May 2006 + + + The IEEE specifications should be consulted concerning the encoding + for signed zero, signed infinity (overflow), and denormalized numbers + (underflow) [IEEE]. According to IEEE specifications, the "NaN" (not + a number) is system dependent and should not be interpreted within + XDR as anything other than "NaN". + +4.7. Double-Precision Floating-Point + + The standard defines the encoding for the double-precision floating- + point data type "double" (64 bits or 8 bytes). The encoding used is + the IEEE standard for normalized double-precision floating-point + numbers [IEEE]. The standard encodes the following three fields, + which describe the double-precision floating-point number: + + S: The sign of the number. Values 0 and 1 represent positive and + negative, respectively. One bit. + + E: The exponent of the number, base 2. 11 bits are devoted to + this field. The exponent is biased by 1023. + + F: The fractional part of the number's mantissa, base 2. 52 bits + are devoted to this field. + + Therefore, the floating-point number is described by: + + (-1)**S * 2**(E-Bias) * 1.F + + It is declared as follows: + + double identifier; + + +------+------+------+------+------+------+------+------+ + |byte 0|byte 1|byte 2|byte 3|byte 4|byte 5|byte 6|byte 7| + S| E | F | + +------+------+------+------+------+------+------+------+ + 1|<--11-->|<-----------------52 bits------------------->| + <-----------------------64 bits-------------------------> + DOUBLE-PRECISION FLOATING-POINT + + Just as the most and least significant bytes of a number are 0 and 3, + the most and least significant bits of a double-precision floating- + point number are 0 and 63. The beginning bit (and most significant + bit) offsets of S, E, and F are 0, 1, and 12, respectively. Note + that these numbers refer to the mathematical positions of the bits, + and NOT to their actual physical locations (which vary from medium to + medium). + + + + + +Eisler Standards Track [Page 7] + +RFC 4506 XDR: External Data Representation Standard May 2006 + + + The IEEE specifications should be consulted concerning the encoding + for signed zero, signed infinity (overflow), and denormalized numbers + (underflow) [IEEE]. According to IEEE specifications, the "NaN" (not + a number) is system dependent and should not be interpreted within + XDR as anything other than "NaN". + +4.8. Quadruple-Precision Floating-Point + + The standard defines the encoding for the quadruple-precision + floating-point data type "quadruple" (128 bits or 16 bytes). The + encoding used is designed to be a simple analog of the encoding used + for single- and double-precision floating-point numbers using one + form of IEEE double extended precision. The standard encodes the + following three fields, which describe the quadruple-precision + floating-point number: + + S: The sign of the number. Values 0 and 1 represent positive and + negative, respectively. One bit. + + E: The exponent of the number, base 2. 15 bits are devoted to + this field. The exponent is biased by 16383. + + F: The fractional part of the number's mantissa, base 2. 112 bits + are devoted to this field. + + Therefore, the floating-point number is described by: + + (-1)**S * 2**(E-Bias) * 1.F + + It is declared as follows: + + quadruple identifier; + + +------+------+------+------+------+------+-...--+------+ + |byte 0|byte 1|byte 2|byte 3|byte 4|byte 5| ... |byte15| + S| E | F | + +------+------+------+------+------+------+-...--+------+ + 1|<----15---->|<-------------112 bits------------------>| + <-----------------------128 bits------------------------> + QUADRUPLE-PRECISION FLOATING-POINT + + Just as the most and least significant bytes of a number are 0 and 3, + the most and least significant bits of a quadruple-precision + floating-point number are 0 and 127. The beginning bit (and most + significant bit) offsets of S, E , and F are 0, 1, and 16, + respectively. Note that these numbers refer to the mathematical + positions of the bits, and NOT to their actual physical locations + (which vary from medium to medium). + + + +Eisler Standards Track [Page 8] + +RFC 4506 XDR: External Data Representation Standard May 2006 + + + The encoding for signed zero, signed infinity (overflow), and + denormalized numbers are analogs of the corresponding encodings for + single and double-precision floating-point numbers [SPAR], [HPRE]. + The "NaN" encoding as it applies to quadruple-precision floating- + point numbers is system dependent and should not be interpreted + within XDR as anything other than "NaN". + +4.9. Fixed-Length Opaque Data + + At times, fixed-length uninterpreted data needs to be passed among + machines. This data is called "opaque" and is declared as follows: + + opaque identifier[n]; + + where the constant n is the (static) number of bytes necessary to + contain the opaque data. If n is not a multiple of four, then the n + bytes are followed by enough (0 to 3) residual zero bytes, r, to make + the total byte count of the opaque object a multiple of four. + + 0 1 ... + +--------+--------+...+--------+--------+...+--------+ + | byte 0 | byte 1 |...|byte n-1| 0 |...| 0 | + +--------+--------+...+--------+--------+...+--------+ + |<-----------n bytes---------->|<------r bytes------>| + |<-----------n+r (where (n+r) mod 4 = 0)------------>| + FIXED-LENGTH OPAQUE + +4.10. Variable-Length Opaque Data + + The standard also provides for variable-length (counted) opaque data, + defined as a sequence of n (numbered 0 through n-1) arbitrary bytes + to be the number n encoded as an unsigned integer (as described + below), and followed by the n bytes of the sequence. + + Byte m of the sequence always precedes byte m+1 of the sequence, and + byte 0 of the sequence always follows the sequence's length (count). + If n is not a multiple of four, then the n bytes are followed by + enough (0 to 3) residual zero bytes, r, to make the total byte count + a multiple of four. Variable-length opaque data is declared in the + following way: + + opaque identifier; + or + opaque identifier<>; + + The constant m denotes an upper bound of the number of bytes that the + sequence may contain. If m is not specified, as in the second + declaration, it is assumed to be (2**32) - 1, the maximum length. + + + +Eisler Standards Track [Page 9] + +RFC 4506 XDR: External Data Representation Standard May 2006 + + + The constant m would normally be found in a protocol specification. + For example, a filing protocol may state that the maximum data + transfer size is 8192 bytes, as follows: + + opaque filedata<8192>; + + 0 1 2 3 4 5 ... + +-----+-----+-----+-----+-----+-----+...+-----+-----+...+-----+ + | length n |byte0|byte1|...| n-1 | 0 |...| 0 | + +-----+-----+-----+-----+-----+-----+...+-----+-----+...+-----+ + |<-------4 bytes------->|<------n bytes------>|<---r bytes--->| + |<----n+r (where (n+r) mod 4 = 0)---->| + VARIABLE-LENGTH OPAQUE + + It is an error to encode a length greater than the maximum described + in the specification. + +4.11. String + + The standard defines a string of n (numbered 0 through n-1) ASCII + bytes to be the number n encoded as an unsigned integer (as described + above), and followed by the n bytes of the string. Byte m of the + string always precedes byte m+1 of the string, and byte 0 of the + string always follows the string's length. If n is not a multiple of + four, then the n bytes are followed by enough (0 to 3) residual zero + bytes, r, to make the total byte count a multiple of four. Counted + byte strings are declared as follows: + + string object; + or + string object<>; + + The constant m denotes an upper bound of the number of bytes that a + string may contain. If m is not specified, as in the second + declaration, it is assumed to be (2**32) - 1, the maximum length. + The constant m would normally be found in a protocol specification. + For example, a filing protocol may state that a file name can be no + longer than 255 bytes, as follows: + + string filename<255>; + + 0 1 2 3 4 5 ... + +-----+-----+-----+-----+-----+-----+...+-----+-----+...+-----+ + | length n |byte0|byte1|...| n-1 | 0 |...| 0 | + +-----+-----+-----+-----+-----+-----+...+-----+-----+...+-----+ + |<-------4 bytes------->|<------n bytes------>|<---r bytes--->| + |<----n+r (where (n+r) mod 4 = 0)---->| + STRING + + + +Eisler Standards Track [Page 10] + +RFC 4506 XDR: External Data Representation Standard May 2006 + + + It is an error to encode a length greater than the maximum described + in the specification. + +4.12. Fixed-Length Array + + Declarations for fixed-length arrays of homogeneous elements are in + the following form: + + type-name identifier[n]; + + Fixed-length arrays of elements numbered 0 through n-1 are encoded by + individually encoding the elements of the array in their natural + order, 0 through n-1. Each element's size is a multiple of four + bytes. Though all elements are of the same type, the elements may + have different sizes. For example, in a fixed-length array of + strings, all elements are of type "string", yet each element will + vary in its length. + + +---+---+---+---+---+---+---+---+...+---+---+---+---+ + | element 0 | element 1 |...| element n-1 | + +---+---+---+---+---+---+---+---+...+---+---+---+---+ + |<--------------------n elements------------------->| + + FIXED-LENGTH ARRAY + +4.13. Variable-Length Array + + Counted arrays provide the ability to encode variable-length arrays + of homogeneous elements. The array is encoded as the element count n + (an unsigned integer) followed by the encoding of each of the array's + elements, starting with element 0 and progressing through element + n-1. The declaration for variable-length arrays follows this form: + + type-name identifier; + or + type-name identifier<>; + + The constant m specifies the maximum acceptable element count of an + array; if m is not specified, as in the second declaration, it is + assumed to be (2**32) - 1. + + 0 1 2 3 + +--+--+--+--+--+--+--+--+--+--+--+--+...+--+--+--+--+ + | n | element 0 | element 1 |...|element n-1| + +--+--+--+--+--+--+--+--+--+--+--+--+...+--+--+--+--+ + |<-4 bytes->|<--------------n elements------------->| + COUNTED ARRAY + + + + +Eisler Standards Track [Page 11] + +RFC 4506 XDR: External Data Representation Standard May 2006 + + + It is an error to encode a value of n that is greater than the + maximum described in the specification. + +4.14. Structure + + Structures are declared as follows: + + struct { + component-declaration-A; + component-declaration-B; + ... + } identifier; + + The components of the structure are encoded in the order of their + declaration in the structure. Each component's size is a multiple of + four bytes, though the components may be different sizes. + + +-------------+-------------+... + | component A | component B |... STRUCTURE + +-------------+-------------+... + +4.15. Discriminated Union + + A discriminated union is a type composed of a discriminant followed + by a type selected from a set of prearranged types according to the + value of the discriminant. The type of discriminant is either "int", + "unsigned int", or an enumerated type, such as "bool". The component + types are called "arms" of the union and are preceded by the value of + the discriminant that implies their encoding. Discriminated unions + are declared as follows: + + union switch (discriminant-declaration) { + case discriminant-value-A: + arm-declaration-A; + case discriminant-value-B: + arm-declaration-B; + ... + default: default-declaration; + } identifier; + + Each "case" keyword is followed by a legal value of the discriminant. + The default arm is optional. If it is not specified, then a valid + encoding of the union cannot take on unspecified discriminant values. + The size of the implied arm is always a multiple of four bytes. + + The discriminated union is encoded as its discriminant followed by + the encoding of the implied arm. + + + + +Eisler Standards Track [Page 12] + +RFC 4506 XDR: External Data Representation Standard May 2006 + + + 0 1 2 3 + +---+---+---+---+---+---+---+---+ + | discriminant | implied arm | DISCRIMINATED UNION + +---+---+---+---+---+---+---+---+ + |<---4 bytes--->| + +4.16. Void + + An XDR void is a 0-byte quantity. Voids are useful for describing + operations that take no data as input or no data as output. They are + also useful in unions, where some arms may contain data and others do + not. The declaration is simply as follows: + + void; + + Voids are illustrated as follows: + + ++ + || VOID + ++ + --><-- 0 bytes + +4.17. Constant + + The data declaration for a constant follows this form: + + const name-identifier = n; + + "const" is used to define a symbolic name for a constant; it does not + declare any data. The symbolic constant may be used anywhere a + regular constant may be used. For example, the following defines a + symbolic constant DOZEN, equal to 12. + + const DOZEN = 12; + +4.18. Typedef + + "typedef" does not declare any data either, but serves to define new + identifiers for declaring data. The syntax is: + + typedef declaration; + + The new type name is actually the variable name in the declaration + part of the typedef. For example, the following defines a new type + called "eggbox" using an existing type called "egg": + + typedef egg eggbox[DOZEN]; + + + + +Eisler Standards Track [Page 13] + +RFC 4506 XDR: External Data Representation Standard May 2006 + + + Variables declared using the new type name have the same type as the + new type name would have in the typedef, if it were considered a + variable. For example, the following two declarations are equivalent + in declaring the variable "fresheggs": + + eggbox fresheggs; egg fresheggs[DOZEN]; + + When a typedef involves a struct, enum, or union definition, there is + another (preferred) syntax that may be used to define the same type. + In general, a typedef of the following form: + + typedef <> identifier; + + may be converted to the alternative form by removing the "typedef" + part and placing the identifier after the "struct", "union", or + "enum" keyword, instead of at the end. For example, here are the two + ways to define the type "bool": + + typedef enum { /* using typedef */ + FALSE = 0, + TRUE = 1 + } bool; + + enum bool { /* preferred alternative */ + FALSE = 0, + TRUE = 1 + }; + + This syntax is preferred because one does not have to wait until the + end of a declaration to figure out the name of the new type. + +4.19. Optional-Data + + Optional-data is one kind of union that occurs so frequently that we + give it a special syntax of its own for declaring it. It is declared + as follows: + + type-name *identifier; + + This is equivalent to the following union: + + union switch (bool opted) { + case TRUE: + type-name element; + case FALSE: + void; + } identifier; + + + + +Eisler Standards Track [Page 14] + +RFC 4506 XDR: External Data Representation Standard May 2006 + + + It is also equivalent to the following variable-length array + declaration, since the boolean "opted" can be interpreted as the + length of the array: + + type-name identifier<1>; + + Optional-data is not so interesting in itself, but it is very useful + for describing recursive data-structures such as linked-lists and + trees. For example, the following defines a type "stringlist" that + encodes lists of zero or more arbitrary length strings: + + struct stringentry { + string item<>; + stringentry *next; + }; + + typedef stringentry *stringlist; + + It could have been equivalently declared as the following union: + + union stringlist switch (bool opted) { + case TRUE: + struct { + string item<>; + stringlist next; + } element; + case FALSE: + void; + }; + + or as a variable-length array: + + struct stringentry { + string item<>; + stringentry next<1>; + }; + + typedef stringentry stringlist<1>; + + Both of these declarations obscure the intention of the stringlist + type, so the optional-data declaration is preferred over both of + them. The optional-data type also has a close correlation to how + recursive data structures are represented in high-level languages + such as Pascal or C by use of pointers. In fact, the syntax is the + same as that of the C language for pointers. + + + + + + +Eisler Standards Track [Page 15] + +RFC 4506 XDR: External Data Representation Standard May 2006 + + +4.20. Areas for Future Enhancement + + The XDR standard lacks representations for bit fields and bitmaps, + since the standard is based on bytes. Also missing are packed (or + binary-coded) decimals. + + The intent of the XDR standard was not to describe every kind of data + that people have ever sent or will ever want to send from machine to + machine. Rather, it only describes the most commonly used data-types + of high-level languages such as Pascal or C so that applications + written in these languages will be able to communicate easily over + some medium. + + One could imagine extensions to XDR that would let it describe almost + any existing protocol, such as TCP. The minimum necessary for this + is support for different block sizes and byte-orders. The XDR + discussed here could then be considered the 4-byte big-endian member + of a larger XDR family. + +5. Discussion + + (1) Why use a language for describing data? What's wrong with + diagrams? + + There are many advantages in using a data-description language such + as XDR versus using diagrams. Languages are more formal than + diagrams and lead to less ambiguous descriptions of data. Languages + are also easier to understand and allow one to think of other issues + instead of the low-level details of bit encoding. Also, there is a + close analogy between the types of XDR and a high-level language such + as C or Pascal. This makes the implementation of XDR encoding and + decoding modules an easier task. Finally, the language specification + itself is an ASCII string that can be passed from machine to machine + to perform on-the-fly data interpretation. + + (2) Why is there only one byte-order for an XDR unit? + + Supporting two byte-orderings requires a higher-level protocol for + determining in which byte-order the data is encoded. Since XDR is + not a protocol, this can't be done. The advantage of this, though, + is that data in XDR format can be written to a magnetic tape, for + example, and any machine will be able to interpret it, since no + higher-level protocol is necessary for determining the byte-order. + + (3) Why is the XDR byte-order big-endian instead of little-endian? + Isn't this unfair to little-endian machines such as the VAX(r), + which has to convert from one form to the other? + + + + +Eisler Standards Track [Page 16] + +RFC 4506 XDR: External Data Representation Standard May 2006 + + + Yes, it is unfair, but having only one byte-order means you have to + be unfair to somebody. Many architectures, such as the Motorola + 68000* and IBM 370*, support the big-endian byte-order. + + (4) Why is the XDR unit four bytes wide? + + There is a tradeoff in choosing the XDR unit size. Choosing a small + size, such as two, makes the encoded data small, but causes alignment + problems for machines that aren't aligned on these boundaries. A + large size, such as eight, means the data will be aligned on + virtually every machine, but causes the encoded data to grow too big. + We chose four as a compromise. Four is big enough to support most + architectures efficiently, except for rare machines such as the + eight-byte-aligned Cray*. Four is also small enough to keep the + encoded data restricted to a reasonable size. + + (5) Why must variable-length data be padded with zeros? + + It is desirable that the same data encode into the same thing on all + machines, so that encoded data can be meaningfully compared or + checksummed. Forcing the padded bytes to be zero ensures this. + + (6) Why is there no explicit data-typing? + + Data-typing has a relatively high cost for what small advantages it + may have. One cost is the expansion of data due to the inserted type + fields. Another is the added cost of interpreting these type fields + and acting accordingly. And most protocols already know what type + they expect, so data-typing supplies only redundant information. + However, one can still get the benefits of data-typing using XDR. + One way is to encode two things: first, a string that is the XDR data + description of the encoded data, and then the encoded data itself. + Another way is to assign a value to all the types in XDR, and then + define a universal type that takes this value as its discriminant and + for each value, describes the corresponding data type. + +6. The XDR Language Specification + +6.1. Notational Conventions + + This specification uses an extended Back-Naur Form notation for + describing the XDR language. Here is a brief description of the + notation: + + (1) The characters '|', '(', ')', '[', ']', '"', and '*' are special. + (2) Terminal symbols are strings of any characters surrounded by + double quotes. (3) Non-terminal symbols are strings of non-special + characters. (4) Alternative items are separated by a vertical bar + + + +Eisler Standards Track [Page 17] + +RFC 4506 XDR: External Data Representation Standard May 2006 + + + ("|"). (5) Optional items are enclosed in brackets. (6) Items are + grouped together by enclosing them in parentheses. (7) A '*' + following an item means 0 or more occurrences of that item. + + For example, consider the following pattern: + + "a " "very" (", " "very")* [" cold " "and "] " rainy " + ("day" | "night") + + An infinite number of strings match this pattern. A few of them are: + + "a very rainy day" + "a very, very rainy day" + "a very cold and rainy day" + "a very, very, very cold and rainy night" + +6.2. Lexical Notes + + (1) Comments begin with '/*' and terminate with '*/'. (2) White + space serves to separate items and is otherwise ignored. (3) An + identifier is a letter followed by an optional sequence of letters, + digits, or underbar ('_'). The case of identifiers is not ignored. + (4) A decimal constant expresses a number in base 10 and is a + sequence of one or more decimal digits, where the first digit is not + a zero, and is optionally preceded by a minus-sign ('-'). (5) A + hexadecimal constant expresses a number in base 16, and must be + preceded by '0x', followed by one or hexadecimal digits ('A', 'B', + 'C', 'D', E', 'F', 'a', 'b', 'c', 'd', 'e', 'f', '0', '1', '2', '3', + '4', '5', '6', '7', '8', '9'). (6) An octal constant expresses a + number in base 8, always leads with digit 0, and is a sequence of one + or more octal digits ('0', '1', '2', '3', '4', '5', '6', '7'). + +6.3. Syntax Information + + declaration: + type-specifier identifier + | type-specifier identifier "[" value "]" + | type-specifier identifier "<" [ value ] ">" + | "opaque" identifier "[" value "]" + | "opaque" identifier "<" [ value ] ">" + | "string" identifier "<" [ value ] ">" + | type-specifier "*" identifier + | "void" + + value: + constant + | identifier + + + + +Eisler Standards Track [Page 18] + +RFC 4506 XDR: External Data Representation Standard May 2006 + + + constant: + decimal-constant | hexadecimal-constant | octal-constant + + type-specifier: + [ "unsigned" ] "int" + | [ "unsigned" ] "hyper" + | "float" + | "double" + | "quadruple" + | "bool" + | enum-type-spec + | struct-type-spec + | union-type-spec + | identifier + + enum-type-spec: + "enum" enum-body + + enum-body: + "{" + ( identifier "=" value ) + ( "," identifier "=" value )* + "}" + + struct-type-spec: + "struct" struct-body + + struct-body: + "{" + ( declaration ";" ) + ( declaration ";" )* + "}" + + union-type-spec: + "union" union-body + + union-body: + "switch" "(" declaration ")" "{" + case-spec + case-spec * + [ "default" ":" declaration ";" ] + "}" + + case-spec: + ( "case" value ":") + ( "case" value ":") * + declaration ";" + + + + +Eisler Standards Track [Page 19] + +RFC 4506 XDR: External Data Representation Standard May 2006 + + + constant-def: + "const" identifier "=" constant ";" + + type-def: + "typedef" declaration ";" + | "enum" identifier enum-body ";" + | "struct" identifier struct-body ";" + | "union" identifier union-body ";" + + definition: + type-def + | constant-def + + specification: + definition * + +6.4. Syntax Notes + + (1) The following are keywords and cannot be used as identifiers: + "bool", "case", "const", "default", "double", "quadruple", "enum", + "float", "hyper", "int", "opaque", "string", "struct", "switch", + "typedef", "union", "unsigned", and "void". + + (2) Only unsigned constants may be used as size specifications for + arrays. If an identifier is used, it must have been declared + previously as an unsigned constant in a "const" definition. + + (3) Constant and type identifiers within the scope of a specification + are in the same name space and must be declared uniquely within this + scope. + + (4) Similarly, variable names must be unique within the scope of + struct and union declarations. Nested struct and union declarations + create new scopes. + + (5) The discriminant of a union must be of a type that evaluates to + an integer. That is, "int", "unsigned int", "bool", an enumerated + type, or any typedefed type that evaluates to one of these is legal. + Also, the case values must be one of the legal values of the + discriminant. Finally, a case value may not be specified more than + once within the scope of a union declaration. + + + + + + + + + + +Eisler Standards Track [Page 20] + +RFC 4506 XDR: External Data Representation Standard May 2006 + + +7. An Example of an XDR Data Description + + Here is a short XDR data description of a thing called a "file", + which might be used to transfer files from one machine to another. + + const MAXUSERNAME = 32; /* max length of a user name */ + const MAXFILELEN = 65535; /* max length of a file */ + const MAXNAMELEN = 255; /* max length of a file name */ + + /* + * Types of files: + */ + enum filekind { + TEXT = 0, /* ascii data */ + DATA = 1, /* raw data */ + EXEC = 2 /* executable */ + }; + + /* + * File information, per kind of file: + */ + union filetype switch (filekind kind) { + case TEXT: + void; /* no extra information */ + case DATA: + string creator; /* data creator */ + case EXEC: + string interpretor; /* program interpretor */ + }; + + /* + * A complete file: + */ + struct file { + string filename; /* name of file */ + filetype type; /* info about file */ + string owner; /* owner of file */ + opaque data; /* file data */ + }; + + Suppose now that there is a user named "john" who wants to store his + lisp program "sillyprog" that contains just the data "(quit)". His + file would be encoded as follows: + + + + + + + + +Eisler Standards Track [Page 21] + +RFC 4506 XDR: External Data Representation Standard May 2006 + + + OFFSET HEX BYTES ASCII COMMENTS + ------ --------- ----- -------- + 0 00 00 00 09 .... -- length of filename = 9 + 4 73 69 6c 6c sill -- filename characters + 8 79 70 72 6f ypro -- ... and more characters ... + 12 67 00 00 00 g... -- ... and 3 zero-bytes of fill + 16 00 00 00 02 .... -- filekind is EXEC = 2 + 20 00 00 00 04 .... -- length of interpretor = 4 + 24 6c 69 73 70 lisp -- interpretor characters + 28 00 00 00 04 .... -- length of owner = 4 + 32 6a 6f 68 6e john -- owner characters + 36 00 00 00 06 .... -- length of file data = 6 + 40 28 71 75 69 (qui -- file data bytes ... + 44 74 29 00 00 t).. -- ... and 2 zero-bytes of fill + +8. Security Considerations + + XDR is a data description language, not a protocol, and hence it does + not inherently give rise to any particular security considerations. + Protocols that carry XDR-formatted data, such as NFSv4, are + responsible for providing any necessary security services to secure + the data they transport. + + Care must be take to properly encode and decode data to avoid + attacks. Known and avoidable risks include: + + * Buffer overflow attacks. Where feasible, protocols should be + defined with explicit limits (via the "<" [ value ] ">" notation + instead of "<" ">") on elements with variable-length data types. + Regardless of the feasibility of an explicit limit on the + variable length of an element of a given protocol, decoders need + to ensure the incoming size does not exceed the length of any + provisioned receiver buffers. + + * Nul octets embedded in an encoded value of type string. If the + decoder's native string format uses nul-terminated strings, then + the apparent size of the decoded object will be less than the + amount of memory allocated for the string. Some memory + deallocation interfaces take a size argument. The caller of the + deallocation interface would likely determine the size of the + string by counting to the location of the nul octet and adding + one. This discrepancy can cause memory leakage (because less + memory is actually returned to the free pool than allocated), + leading to system failure and a denial of service attack. + + * Decoding of characters in strings that are legal ASCII + characters but nonetheless are illegal for the intended + application. For example, some operating systems treat the '/' + + + +Eisler Standards Track [Page 22] + +RFC 4506 XDR: External Data Representation Standard May 2006 + + + character as a component separator in path names. For a + protocol that encodes a string in the argument to a file + creation operation, the decoder needs to ensure that '/' is not + inside the component name. Otherwise, a file with an illegal + '/' in its name will be created, making it difficult to remove, + and is therefore a denial of service attack. + + * Denial of service caused by recursive decoder or encoder + subroutines. A recursive decoder or encoder might process data + that has a structured type with a member of type optional data + that directly or indirectly refers to the structured type (i.e., + a linked list). For example, + + struct m { + int x; + struct m *next; + }; + + An encoder or decoder subroutine might be written to recursively + call itself each time another element of type "struct m" is + found. An attacker could construct a long linked list of + "struct m" elements in the request or response, which then + causes a stack overflow on the decoder or encoder. Decoders and + encoders should be written non-recursively or impose a limit on + list length. + +9. IANA Considerations + + It is possible, if not likely, that new data types will be added to + XDR in the future. The process for adding new types is via a + standards track RFC and not registration of new types with IANA. + Standards track RFCs that update or replace this document should be + documented as such in the RFC Editor's database of RFCs. + +10. Trademarks and Owners + + SUN WORKSTATION Sun Microsystems, Inc. + VAX Hewlett-Packard Company + IBM-PC International Business Machines Corporation + Cray Cray Inc. + NFS Sun Microsystems, Inc. + Ethernet Xerox Corporation. + Motorola 68000 Motorola, Inc. + IBM 370 International Business Machines Corporation + + + + + + + +Eisler Standards Track [Page 23] + +RFC 4506 XDR: External Data Representation Standard May 2006 + + +11. ANSI/IEEE Standard 754-1985 + + The definition of NaNs, signed zero and infinity, and denormalized + numbers from [IEEE] is reproduced here for convenience. The + definitions for quadruple-precision floating point numbers are + analogs of those for single and double-precision floating point + numbers and are defined in [IEEE]. + + In the following, 'S' stands for the sign bit, 'E' for the exponent, + and 'F' for the fractional part. The symbol 'u' stands for an + undefined bit (0 or 1). + + For single-precision floating point numbers: + + Type S (1 bit) E (8 bits) F (23 bits) + ---- --------- ---------- ----------- + signalling NaN u 255 (max) .0uuuuu---u + (with at least + one 1 bit) + quiet NaN u 255 (max) .1uuuuu---u + + negative infinity 1 255 (max) .000000---0 + + positive infinity 0 255 (max) .000000---0 + + negative zero 1 0 .000000---0 + + positive zero 0 0 .000000---0 + + For double-precision floating point numbers: + + Type S (1 bit) E (11 bits) F (52 bits) + ---- --------- ----------- ----------- + signalling NaN u 2047 (max) .0uuuuu---u + (with at least + one 1 bit) + quiet NaN u 2047 (max) .1uuuuu---u + + negative infinity 1 2047 (max) .000000---0 + + positive infinity 0 2047 (max) .000000---0 + + negative zero 1 0 .000000---0 + + positive zero 0 0 .000000---0 + + + + + + +Eisler Standards Track [Page 24] + +RFC 4506 XDR: External Data Representation Standard May 2006 + + + For quadruple-precision floating point numbers: + + Type S (1 bit) E (15 bits) F (112 bits) + ---- --------- ----------- ------------ + signalling NaN u 32767 (max) .0uuuuu---u + (with at least + one 1 bit) + quiet NaN u 32767 (max) .1uuuuu---u + + negative infinity 1 32767 (max) .000000---0 + + positive infinity 0 32767 (max) .000000---0 + + negative zero 1 0 .000000---0 + + positive zero 0 0 .000000---0 + + Subnormal numbers are represented as follows: + + Precision Exponent Value + --------- -------- ----- + Single 0 (-1)**S * 2**(-126) * 0.F + + Double 0 (-1)**S * 2**(-1022) * 0.F + + Quadruple 0 (-1)**S * 2**(-16382) * 0.F + +12. Normative References + + [IEEE] "IEEE Standard for Binary Floating-Point Arithmetic", + ANSI/IEEE Standard 754-1985, Institute of Electrical and + Electronics Engineers, August 1985. + +13. Informative References + + [KERN] Brian W. Kernighan & Dennis M. Ritchie, "The C Programming + Language", Bell Laboratories, Murray Hill, New Jersey, 1978. + + [COHE] Danny Cohen, "On Holy Wars and a Plea for Peace", IEEE + Computer, October 1981. + + [COUR] "Courier: The Remote Procedure Call Protocol", XEROX + Corporation, XSIS 038112, December 1981. + + [SPAR] "The SPARC Architecture Manual: Version 8", Prentice Hall, + ISBN 0-13-825001-4. + + [HPRE] "HP Precision Architecture Handbook", June 1987, 5954-9906. + + + +Eisler Standards Track [Page 25] + +RFC 4506 XDR: External Data Representation Standard May 2006 + + +14. Acknowledgements + + Bob Lyon was Sun's visible force behind ONC RPC in the 1980s. Sun + Microsystems, Inc., is listed as the author of RFC 1014. Raj + Srinivasan and the rest of the old ONC RPC working group edited RFC + 1014 into RFC 1832, from which this document is derived. Mike Eisler + and Bill Janssen submitted the implementation reports for this + standard. Kevin Coffman, Benny Halevy, and Jon Peterson reviewed + this document and gave feedback. Peter Astrand and Bryan Olson + pointed out several errors in RFC 1832 which are corrected in this + document. + +Editor's Address + + Mike Eisler + 5765 Chase Point Circle + Colorado Springs, CO 80919 + USA + + Phone: 719-599-9026 + EMail: email2mre-rfc4506@yahoo.com + + Please address comments to: nfsv4@ietf.org + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Eisler Standards Track [Page 26] + +RFC 4506 XDR: External Data Representation Standard May 2006 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2006). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET + ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, + INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE + INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is provided by the IETF + Administrative Support Activity (IASA). + + + + + + + +Eisler Standards Track [Page 27] + diff --git a/src/xdr/index.ts b/src/xdr/index.ts index a4ce226e..5d7a9eb2 100644 --- a/src/xdr/index.ts +++ b/src/xdr/index.ts @@ -1,8 +1,16 @@ /** * XDR (External Data Representation Standard) module * - * This module provides TypeScript type definitions and encoder implementations - * for XDR schemas based on RFC 4506 specification. + * Fully compliant with: + * - RFC 4506 (May 2006) - Current standard with IANA and security considerations + * - RFC 1832 (August 1995) - Enhanced standard with quadruple floats and optional-data + * - RFC 1014 (June 1987) - Original standard + * + * Features: + * - All XDR data types (int, hyper, float, double, string, opaque, arrays, structs, unions, optional-data) + * - Big-endian byte order with 4-byte alignment + * - Schema-based encoding/decoding with validation + * - TypeScript definitions */ export * from './types'; diff --git a/src/xdr/types.ts b/src/xdr/types.ts index 68ded380..fc0d02df 100644 --- a/src/xdr/types.ts +++ b/src/xdr/types.ts @@ -1,9 +1,16 @@ /** * XDR (External Data Representation Standard) schema type definitions - * based on RFC 4506 specification. + * based on RFC 4506 (May 2006), which obsoletes RFC 1832 (August 1995) + * and RFC 1014 (June 1987). + * + * This implementation supports all three RFC versions: + * - RFC 1014: Original XDR standard + * - RFC 1832: Added quadruple-precision floats, enhanced optional-data + * - RFC 4506: Added IANA considerations and security guidance (no protocol changes) + * * Specification: https://datatracker.ietf.org/doc/html/rfc4506 */ -export type XdrSchema = XdrPrimitiveSchema | XdrWidePrimitiveSchema | XdrCompositeSchema; +export type XdrSchema = XdrPrimitiveSchema | XdrWidePrimitiveSchema | XdrCompositeSchema | XdrOptionalSchema; // Primitive type schemas @@ -50,7 +57,13 @@ export interface XdrStringSchema extends XdrBaseSchema<'string'> { // Composite type schemas -export type XdrCompositeSchema = XdrArraySchema | XdrVarlenArraySchema | XdrStructSchema | XdrUnionSchema; +export type XdrCompositeSchema = + | XdrArraySchema + | XdrVarlenArraySchema + | XdrStructSchema + | XdrUnionSchema + | XdrOptionalSchema + | XdrConstantSchema; export interface XdrArraySchema extends XdrBaseSchema<'array'> { /** Schema of array elements */ @@ -90,6 +103,29 @@ export interface XdrUnionSchema extends XdrBaseSchema<'union'> { default?: XdrSchema; } +/** + * Optional-data is a special case introduced in RFC 1832. + * It is syntactic sugar for a union with a boolean discriminant: + * type *identifier; + * is equivalent to: + * union switch (bool opted) { + * case TRUE: type element; + * case FALSE: void; + * } + */ +export interface XdrOptionalSchema extends XdrBaseSchema<'optional'> { + /** Schema of the optional element */ + element: XdrSchema; +} + +/** + * Constant definition (RFC 4506 Section 4.17). + * Constants are used to define symbolic names for numeric values. + */ +export interface XdrConstantSchema extends XdrBaseSchema<'const'> { + value: number; +} + // Base schema export interface XdrBaseSchema { diff --git a/tslint.json b/tslint.json index 97f7af1b..9f251907 100644 --- a/tslint.json +++ b/tslint.json @@ -14,6 +14,7 @@ "no-angle-bracket-type-assertion": false, "ban-comma-operator": false, "no-unused-expression": false, - "no-implicit-dependencies": false + "no-implicit-dependencies": false, + "label-position": false } } diff --git a/yarn.lock b/yarn.lock index 191dc09a..82da1e87 100644 --- a/yarn.lock +++ b/yarn.lock @@ -605,24 +605,23 @@ resolved "https://registry.yarnpkg.com/@jsonjoy.com/buffers/-/buffers-1.0.0.tgz#ade6895b7d3883d70f87b5743efaa12c71dfef7a" integrity sha512-NDigYR3PHqCnQLXYyoLbnEdzMMvzeiCWo1KOut7Q0CoIqg9tUAPKJ1iq/2nFhc5kZtexzutNY0LFjdwWL3Dw3Q== +"@jsonjoy.com/buffers@^1.2.0": + version "1.2.0" + resolved "https://registry.yarnpkg.com/@jsonjoy.com/buffers/-/buffers-1.2.0.tgz#57b9bbc509055de80f22cf6b696ac7efd7554046" + integrity sha512-6RX+W5a+ZUY/c/7J5s5jK9UinLfJo5oWKh84fb4X0yK2q4WXEWUWZWuEMjvCb1YNUQhEAhUfr5scEGOH7jC4YQ== + "@jsonjoy.com/codegen@^1.0.0": version "1.0.0" resolved "https://registry.yarnpkg.com/@jsonjoy.com/codegen/-/codegen-1.0.0.tgz#5c23f796c47675f166d23b948cdb889184b93207" integrity sha512-E8Oy+08cmCf0EK/NMxpaJZmOxPqM+6iSe2S4nlSBrPZOORoDJILxtbSUEDKQyTamm/BVAhIGllOBNU79/dwf0g== -"@jsonjoy.com/json-pointer@^1.0.1": - version "1.0.1" - resolved "https://registry.yarnpkg.com/@jsonjoy.com/json-pointer/-/json-pointer-1.0.1.tgz#3b710158e8a212708a2886ea5e38d92e2ea4f4a0" - integrity sha512-tJpwQfuBuxqZlyoJOSZcqf7OUmiYQ6MiPNmOv4KbZdXE/DdvBSSAwhos0zIlJU/AXxC8XpuO8p08bh2fIl+RKA== - dependencies: - "@jsonjoy.com/util" "^1.3.0" - -"@jsonjoy.com/util@^1.3.0": - version "1.8.1" - resolved "https://registry.yarnpkg.com/@jsonjoy.com/util/-/util-1.8.1.tgz#62387224001e59ded1ca3744b88b44cdb808e7f9" - integrity sha512-26hOMkQx15sYBpt/bCK3/S7Bep8vMy+VKGBhWQax7GXYd+mwP5mc0HNX5oqLws/JQZ9GRjn9rvXoDbcq1OC2xA== +"@jsonjoy.com/json-pointer@^1.0.2": + version "1.0.2" + resolved "https://registry.yarnpkg.com/@jsonjoy.com/json-pointer/-/json-pointer-1.0.2.tgz#049cb530ac24e84cba08590c5e36b431c4843408" + integrity sha512-Fsn6wM2zlDzY1U+v4Nc8bo3bVqgfNTGcn6dMgs6FjrEnt4ZCe60o6ByKRjOGlI2gow0aE/Q41QOigdTqkyK5fg== dependencies: - "@jsonjoy.com/buffers" "^1.0.0" + "@jsonjoy.com/codegen" "^1.0.0" + "@jsonjoy.com/util" "^1.9.0" "@jsonjoy.com/util@^1.9.0": version "1.9.0"