diff options
212 files changed, 5240 insertions, 30707 deletions
diff --git a/OTP_VERSION b/OTP_VERSION index 39626521cb..5f8e72c36b 100644 --- a/OTP_VERSION +++ b/OTP_VERSION @@ -1 +1 @@ -18.1.4 +18.1.5 diff --git a/erts/aclocal.m4 b/erts/aclocal.m4 index 390d6cfc4d..3d52538933 100644 --- a/erts/aclocal.m4 +++ b/erts/aclocal.m4 @@ -142,18 +142,18 @@ MIXED_MSYS=no AC_MSG_CHECKING(for mixed cygwin or msys and native VC++ environment) if test "X$host" = "Xwin32" -a "x$GCC" != "xyes"; then - if test -x /usr/bin/cygpath; then - CFLAGS="-O2" - MIXED_CYGWIN=yes - AC_MSG_RESULT([Cygwin and VC]) - MIXED_CYGWIN_VC=yes - CPPFLAGS="$CPPFLAGS -DERTS_MIXED_CYGWIN_VC" - elif test -x /usr/bin/msysinfo; then + if test -x /usr/bin/msys-?.0.dll; then CFLAGS="-O2" MIXED_MSYS=yes AC_MSG_RESULT([MSYS and VC]) MIXED_MSYS_VC=yes CPPFLAGS="$CPPFLAGS -DERTS_MIXED_MSYS_VC" + elif test -x /usr/bin/cygpath; then + CFLAGS="-O2" + MIXED_CYGWIN=yes + AC_MSG_RESULT([Cygwin and VC]) + MIXED_CYGWIN_VC=yes + CPPFLAGS="$CPPFLAGS -DERTS_MIXED_CYGWIN_VC" else AC_MSG_RESULT([undeterminable]) AC_MSG_ERROR(Seems to be mixed windows but not with cygwin, cannot handle this!) diff --git a/erts/doc/src/absform.xml b/erts/doc/src/absform.xml index df2553ced3..ca06794a53 100644 --- a/erts/doc/src/absform.xml +++ b/erts/doc/src/absform.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + </legalnotice> <title>The Abstract Format</title> @@ -35,24 +35,24 @@ <p></p> <p>This document describes the standard representation of parse trees for Erlang programs as Erlang terms. This representation is known as the <em>abstract format</em>. - Functions dealing with such parse trees are <c><![CDATA[compile:forms/[1,2]]]></c> + Functions dealing with such parse trees are <c>compile:forms/[1,2]</c> and functions in the modules - <c><![CDATA[epp]]></c>, - <c><![CDATA[erl_eval]]></c>, - <c><![CDATA[erl_lint]]></c>, - <c><![CDATA[erl_pp]]></c>, - <c><![CDATA[erl_parse]]></c>, + <c>epp</c>, + <c>erl_eval</c>, + <c>erl_lint</c>, + <c>erl_pp</c>, + <c>erl_parse</c>, and - <c><![CDATA[io]]></c>. + <c>io</c>. They are also used as input and output for parse transforms (see the module - <c><![CDATA[compile]]></c>).</p> - <p>We use the function <c><![CDATA[Rep]]></c> to denote the mapping from an Erlang source - construct <c><![CDATA[C]]></c> to its abstract format representation <c><![CDATA[R]]></c>, and write - <c><![CDATA[R = Rep(C)]]></c>. + <c>compile</c>).</p> + <p>We use the function <c>Rep</c> to denote the mapping from an Erlang source + construct <c>C</c> to its abstract format representation <c>R</c>, and write + <c>R = Rep(C)</c>. </p> - <p>The word <c><![CDATA[LINE]]></c> below represents an integer, and denotes the + <p>The word <c>LINE</c> below represents an integer, and denotes the number of the line in the source file where the construction occurred. - Several instances of <c><![CDATA[LINE]]></c> in the same construction may denote + Several instances of <c>LINE</c> in the same construction may denote different lines.</p> <p>Since operators are not terms in their own right, when operators are mentioned below, the representation of an operator should be taken to @@ -61,233 +61,116 @@ </p> <section> - <title>Module declarations and forms</title> + <title>Module Declarations and Forms</title> <p>A module declaration consists of a sequence of forms that are either function declarations or attributes.</p> <list type="bulleted"> <item>If D is a module declaration consisting of the forms - <c><![CDATA[F_1]]></c>, ..., <c><![CDATA[F_k]]></c>, then - Rep(D) = <c><![CDATA[[Rep(F_1), ..., Rep(F_k)]]]></c>.</item> - <item>If F is an attribute <c><![CDATA[-module(Mod)]]></c>, then - Rep(F) = <c><![CDATA[{attribute,LINE,module,Mod}]]></c>.</item> - <item>If F is an attribute <c><![CDATA[-behavior(Behavior)]]></c>, then - Rep(F) = <c><![CDATA[{attribute,LINE,behavior,Behavior}]]></c>.</item> - <item>If F is an attribute <c><![CDATA[-behaviour(Behaviour)]]></c>, then - Rep(F) = <c><![CDATA[{attribute,LINE,behaviour,Behaviour}]]></c>.</item> - <item>If F is an attribute <c><![CDATA[-export([Fun_1/A_1, ..., Fun_k/A_k])]]></c>, then - Rep(F) = <c><![CDATA[{attribute,LINE,export,[{Fun_1,A_1}, ..., {Fun_k,A_k}]}]]></c>.</item> - <item>If F is an attribute <c><![CDATA[-import(Mod,[Fun_1/A_1, ..., Fun_k/A_k])]]></c>, then - Rep(F) = <c><![CDATA[{attribute,LINE,import,{Mod,[{Fun_1,A_1}, ..., {Fun_k,A_k}]}}]]></c>.</item> - <item>If F is an attribute <c><![CDATA[-compile(Options)]]></c>, then - Rep(F) = <c><![CDATA[{attribute,LINE,compile,Options}]]></c>.</item> - <item>If F is an attribute <c><![CDATA[-file(File,Line)]]></c>, then - Rep(F) = <c><![CDATA[{attribute,LINE,file,{File,Line}}]]></c>.</item> - <item>If F is a record declaration <c><![CDATA[-record(Name,{V_1, ..., V_k})]]></c>, then - Rep(F) = - <c><![CDATA[{attribute,LINE,record,{Name,[Rep(V_1), ..., Rep(V_k)]}}]]></c>. For Rep(V), see below.</item> - <item>If F is a type attribute (i.e. <c><![CDATA[opaque]]></c> or - <c><![CDATA[type]]></c>) - <c><![CDATA[-Attr Name(A_1, ..., A_k) :: T]]></c> where each - <c><![CDATA[A_i]]></c> is a variable, then Rep(F) = - <c><![CDATA[{attribute,LINE,Attr,{Name,Rep(T),[Rep(A_1), ..., Rep(A_k)]}}]]></c>. - For Rep(T), see below.</item> - <item>If F is a type spec (i.e. <c><![CDATA[callback]]></c> or - <c><![CDATA[spec]]></c>) - <c><![CDATA[-Attr F Tc_1; ...; Tc_k]]></c>, - where each <c><![CDATA[Tc_i]]></c> is a fun type clause with an - argument sequence of the same length <c><![CDATA[Arity]]></c>, then - Rep(F) = - <c><![CDATA[{Attr,LINE,{{F,Arity},[Rep(Tc_1), ..., Rep(Tc_k)]}}]]></c>. - For Rep(Tc_i), see below.</item> - <item>If F is a type spec (i.e. <c><![CDATA[callback]]></c> or - <c><![CDATA[spec]]></c>) - <c><![CDATA[-Attr Mod:F Tc_1; ...; Tc_k]]></c>, - where each <c><![CDATA[Tc_i]]></c> is a fun type clause with an - argument sequence of the same length <c><![CDATA[Arity]]></c>, then - Rep(F) = - <c><![CDATA[{Attr,LINE,{{Mod,F,Arity},[Rep(Tc_1), ..., Rep(Tc_k)]}}]]></c>. - For Rep(Tc_i), see below.</item> - <item>If F is a wild attribute <c><![CDATA[-A(T)]]></c>, then - Rep(F) = <c><![CDATA[{attribute,LINE,A,T}]]></c>. + <c>F_1</c>, ..., <c>F_k</c>, then + Rep(D) = <c>[Rep(F_1), ..., Rep(F_k)]</c>.</item> + <item>If F is an attribute <c>-module(Mod)</c>, then + Rep(F) = <c>{attribute,LINE,module,Mod}</c>.</item> + <item>If F is an attribute <c>-behavior(Behavior)</c>, then + Rep(F) = <c>{attribute,LINE,behavior,Behavior}</c>.</item> + <item>If F is an attribute <c>-behaviour(Behaviour)</c>, then + Rep(F) = <c>{attribute,LINE,behaviour,Behaviour}</c>.</item> + <item>If F is an attribute <c>-export([Fun_1/A_1, ..., Fun_k/A_k])</c>, then + Rep(F) = <c>{attribute,LINE,export,[{Fun_1,A_1}, ..., {Fun_k,A_k}]}</c>.</item> + <item>If F is an attribute <c>-import(Mod,[Fun_1/A_1, ..., Fun_k/A_k])</c>, then + Rep(F) = <c>{attribute,LINE,import,{Mod,[{Fun_1,A_1}, ..., {Fun_k,A_k}]}}</c>.</item> + <item>If F is an attribute <c>-export_type([Type_1/A_1, ..., Type_k/A_k])</c>, then + Rep(F) = <c>{attribute,LINE,export_type,[{Type_1,A_1}, ..., {Type_k,A_k}]}</c>.</item> + <item>If F is an attribute <c>-compile(Options)</c>, then + Rep(F) = <c>{attribute,LINE,compile,Options}</c>.</item> + <item>If F is an attribute <c>-file(File,Line)</c>, then + Rep(F) = <c>{attribute,LINE,file,{File,Line}}</c>.</item> + <item>If F is a record declaration + <c>-record(Name,{V_1, ..., V_k})</c>, then Rep(F) = + <c>{attribute,LINE,record,{Name,[Rep(V_1), ..., Rep(V_k)]}}</c>. + For Rep(V), see below.</item> + <item>If F is a type declaration + <c>-Type Name(V_1, ..., V_k) :: T</c>, where + <c>Type</c> is either the atom <c>type</c> or the atom <c>opaque</c>, + each <c>V_i</c> is a variable, and <c>T</c> is a type, then Rep(F) = + <c>{attribute,LINE,Type,{Name,Rep(T),[Rep(V_1), ..., Rep(V_k)]}}</c>. + </item> + <item>If F is a function specification + <c>-Spec Name Ft_1; ...; Ft_k</c>, + where <c>Spec</c> is either the atom <c>spec</c> or the atom + <c>callback</c>, and each <c>Ft_i</c> is a possibly constrained + function type with an argument sequence of the same length + <c>Arity</c>, then Rep(F) = + <c>{attribute,Line,Spec,{{Name,Arity},[Rep(Ft_1), ..., Rep(Ft_k)]}}</c>. + </item> + <item>If F is a function specification + <c>-spec Mod:Name Ft_1; ...; Ft_k</c>, + where each <c>Ft_i</c> is a possibly constrained + function type with an argument sequence of the same length + <c>Arity</c>, then Rep(F) = + <c>{attribute,Line,spec,{{Mod,Name,Arity},[Rep(Ft_1), ..., Rep(Ft_k)]}}</c>. + </item> + <item>If F is a wild attribute <c>-A(T)</c>, then + Rep(F) = <c>{attribute,LINE,A,T}</c>. <br></br></item> - <item>If F is a function declaration <c><![CDATA[Name Fc_1 ; ... ; Name Fc_k]]></c>, - where each <c><![CDATA[Fc_i]]></c> is a function clause with a - pattern sequence of the same length <c><![CDATA[Arity]]></c>, then - Rep(F) = <c><![CDATA[{function,LINE,Name,Arity,[Rep(Fc_1), ...,Rep(Fc_k)]}]]></c>.</item> + <item>If F is a function declaration + <c>Name Fc_1 ; ... ; Name Fc_k</c>, + where each <c>Fc_i</c> is a function clause with a + pattern sequence of the same length <c>Arity</c>, then + Rep(F) = <c>{function,LINE,Name,Arity,[Rep(Fc_1), ...,Rep(Fc_k)]}</c>. + </item> </list> <section> - <title>Type clauses</title> - <list type="bulleted"> - <item>If T is a fun type clause - <c><![CDATA[(A_1, ..., A_n) -> Ret]]></c>, where each - <c><![CDATA[A_i]]></c> and <c><![CDATA[Ret]]></c> are types, then - Rep(T) = - <c><![CDATA[{type,LINE,'fun',[{type,LINE,product,[Rep(A_1), ..., Rep(A_n)]},Rep(Ret)]}]]></c>. - </item> - <item>If T is a bounded fun type clause <c><![CDATA[Tc when Tg]]></c>, - where <c><![CDATA[Tc]]></c> is an unbounded fun type clause and - <c><![CDATA[Tg]]></c> is a type guard sequence, then Rep(T) = - <c><![CDATA[{type,LINE,bounded_fun,[Rep(Tc),Rep(Tg)]}]]></c>.</item> - </list> - </section> - - <section> - <title>Type guards</title> - <list type="bulleted"> - <item>If G is a constraint <c><![CDATA[F(A_1, ..., A_k)]]></c>, where - <c><![CDATA[F]]></c> is an atom and each <c><![CDATA[A_i]]></c> is a - type, then Rep(G) = - <c><![CDATA[{type,LINE,constraint,[Rep(F),[Rep(A_1), ..., Rep(A_k)]]}]]></c>. - </item> - <item>If G is a type definition <c><![CDATA[Name :: Type]]></c>, - where <c><![CDATA[Name]]></c> is a variable and - <c><![CDATA[Type]]></c> is a type, then Rep(G) = - <c><![CDATA[{type,LINE,constraint,[{atom,LINE,is_subtype},[Rep(Name),Rep(Type)]]}]]></c>.</item> - </list> - </section> - - <section> - <title>Types</title> + <title>Record Fields</title> + <p>Each field in a record declaration may have an optional + explicit default initializer expression, as well as an + optional type.</p> <list type="bulleted"> - <item>If T is a type definition <c><![CDATA[Name :: Type]]></c>, - where <c><![CDATA[Name]]></c> is a variable and - <c><![CDATA[Type]]></c> is a type, then Rep(T) = - <c><![CDATA[{ann_type,LINE,[Rep(Name),Rep(Type)]}]]></c>.</item> - <item>If T is a type union <c><![CDATA[A_1 | ... | A_k]]></c>, - where each <c><![CDATA[A_i]]></c> is a type, then Rep(T) = - <c><![CDATA[{type,LINE,union,[Rep(A_1), ..., Rep(A_k)]}]]></c>.</item> - <item>If T is a type range <c><![CDATA[L .. R]]></c>, - where <c><![CDATA[L]]></c> and <c><![CDATA[R]]></c> are types, then - Rep(T) = <c><![CDATA[{type,LINE,range,[Rep(L), Rep(R)]}]]></c>.</item> - <item>If T is a binary operation <c><![CDATA[L Op R]]></c>, - where <c><![CDATA[Op]]></c> is an arithmetic or bitwise binary operator - and <c><![CDATA[L]]></c> and <c><![CDATA[R]]></c> are types, then - Rep(T) = <c><![CDATA[{op,LINE,Op,Rep(L),Rep(R)}]]></c>.</item> - <item>If T is <c><![CDATA[Op A]]></c>, where <c><![CDATA[Op]]></c> is an - arithmetic or bitwise unary operator and <c><![CDATA[A]]></c> is a - type, then Rep(T) = <c><![CDATA[{op,LINE,Op,Rep(A)}]]></c>.</item> - <item>If T is a fun type <c><![CDATA[fun()]]></c>, then Rep(T) = - <c><![CDATA[{type,LINE,'fun',[]}]]></c>.</item> - <item>If T is a variable <c><![CDATA[V]]></c>, then Rep(T) = - <c><![CDATA[{var,LINE,A}]]></c>, where <c><![CDATA[A]]></c> is an atom - with a printname consisting of the same characters as - <c><![CDATA[V]]></c>.</item> - <item>If T is an atomic literal L and L is not a string literal, then - Rep(T) = Rep(L).</item> - <item>If T is a tuple or map type <c><![CDATA[F()]]></c> (i.e. - <c><![CDATA[tuple]]></c> or <c><![CDATA[map]]></c>), then Rep(T) = - <c><![CDATA[{type,LINE,F,any}]]></c>.</item> - <item>If T is a type <c><![CDATA[F(A_1, ..., A_k)]]></c>, where each - <c><![CDATA[A_i]]></c> is a type, then Rep(T) = - <c><![CDATA[{user_type,LINE,F,[Rep(A_1), ..., Rep(A_k)]}]]></c>.</item> - <item>If T is a remote type <c><![CDATA[M:F(A_1, ..., A_k)]]></c>, where - each <c><![CDATA[A_i]]></c> is a type and <c><![CDATA[M]]></c> and - <c><![CDATA[F]]></c>, then Rep(T) = - <c><![CDATA[{remote_type,LINE,[Rep(M),Rep(F),[Rep(A_1), ..., Rep(A_k)]]}]]></c>. + <item>If V is <c>A</c>, then + Rep(V) = <c>{record_field,LINE,Rep(A)}</c>.</item> + <item>If V is <c>A = E</c>, + where <c>E</c> is an expression, then + Rep(V) = <c>{record_field,LINE,Rep(A),Rep(E)}</c>.</item> + <item>If V is <c>A :: T</c>, where <c>T</c> is a + type and it does not contain + <c>undefined</c> syntactically, then Rep(V) = + <c>{typed_record_field,{record_field,LINE,Rep(A)},Rep(undefined | T)}</c>. </item> - <item>If T is the nil type <c><![CDATA[[]]]></c>, then Rep(T) = - <c><![CDATA[{type,LINE,nil,[]}]]></c>.</item> - <item>If T is a list type <c><![CDATA[[A]]]></c>, where - <c><![CDATA[A]]></c> is a type, then Rep(T) = - <c><![CDATA[{type,LINE,list,[Rep(A)]}]]></c>.</item> - <item>If T is a non-empty list type <c><![CDATA[[A, ...]]]></c>, where - <c><![CDATA[A]]></c> is a type, then Rep(T) = - <c><![CDATA[{type,LINE,nonempty_list,[Rep(A)]}]]></c>.</item> - <item>If T is a map type <c><![CDATA[#{P_1, ..., P_k}]]></c>, where each - <c><![CDATA[P_i]]></c> is a map pair type, then Rep(T) = - <c><![CDATA[{type,LINE,map,[Rep(P_1), ..., Rep(P_k)]}]]></c>.</item> - <item>If T is a map pair type <c><![CDATA[K => V]]></c>, where - <c><![CDATA[K]]></c> and <c><![CDATA[V]]></c> are types, - then Rep(T) = - <c><![CDATA[{type,LINE,map_field_assoc,[Rep(K),Rep(V)]}]]></c>.</item> - <item>If T is a tuple type <c><![CDATA[{A_1, ..., A_k}]]></c>, where - each <c><![CDATA[A_i]]></c> is a type, then Rep(T) = - <c><![CDATA[{type,LINE,tuple,[Rep(A_1), ..., Rep(A_k)]}]]></c>.</item> - <item>If T is a record type <c><![CDATA[#Name{}]]></c>, where - <c><![CDATA[Name]]></c> is an atom, then Rep(T) = - <c><![CDATA[{type,LINE,record,[Rep(Name)]}]]></c>.</item> - <item>If T is a record type <c><![CDATA[#Name{F_1, ..., F_k}]]></c>, - where <c><![CDATA[Name]]></c> is an atom, then Rep(T) = - <c><![CDATA[{type,LINE,record,[Rep(Name),[Rep(F_1), ..., Rep(F_k)]]}]]></c>. + <item>If V is <c>A :: T</c>, where <c>T</c> is a type, then Rep(V) = + <c>{typed_record_field,{record_field,LINE,Rep(A)},Rep(T)}</c>. + </item> + <item>If V is <c>A = E :: T</c>, where + <c>E</c> is an expression and <c>T</c> is a type, then Rep(V) = + <c>{typed_record_field,{record_field,LINE,Rep(A),Rep(E)},Rep(T)}</c>. </item> - <item>If T is a record field type <c><![CDATA[Name :: Type]]></c>, - where <c><![CDATA[Name]]></c> is an atom, then Rep(T) = - <c><![CDATA[{type,LINE,field_type,[Rep(Name),Rep(Type)]}]]></c>.</item> - <item>If T is a record field type <c><![CDATA[<<>>]]></c>, then Rep(T) = - <c><![CDATA[{type,LINE,binary,[{integer,LINE,0},{integer,LINE,0}]}]]></c>. - </item> - <item>If T is a binary type <c><![CDATA[<< _ : B >>]]></c>, where - <c><![CDATA[B]]></c> is a type, then Rep(T) = - <c><![CDATA[{type,LINE,binary,[Rep(B),{integer,LINE,0}]}]]></c>.</item> - <item>If T is a binary type <c><![CDATA[<< _ : _ * U >>]]></c>, - where <c><![CDATA[U]]></c> is a type, then Rep(T) = - <c><![CDATA[{type,LINE,binary,[{integer,LINE,0},Rep(U)]}]]></c>.</item> - <item>If T is a binary type <c><![CDATA[<< _ : B , _ : _ * U >>]]></c>, - where <c><![CDATA[B]]></c> and <c><![CDATA[U]]></c> is a type, then - Rep(T) = - <c><![CDATA[{type,LINE,binary,[Rep(B),Rep(U)]}]]></c>.</item> - - <item>If T is a fun type <c><![CDATA[fun((...) -> Ret)]]></c>, then - Rep(T) = <c><![CDATA[{type,LINE,'fun',[{type,LINE,product,[]},Rep(Ret)]}]]></c>. - </item> - <item>If T is a fun type <c><![CDATA[fun(Tc)]]></c>, where - <c><![CDATA[Tc]]></c> is an unbounded fun type clause, - then Rep(T) = <c><![CDATA[Rep(Tc)]]></c>.</item> </list> </section> <section> - <title>Record fields</title> - <p>Each field in a record declaration may have an optional - explicit default initializer expression</p> - <list type="bulleted"> - <item>If V is <c><![CDATA[A]]></c>, then - Rep(V) = <c><![CDATA[{record_field,LINE,Rep(A)}]]></c>.</item> - <item>If V is <c><![CDATA[A = E]]></c>, then - Rep(V) = <c><![CDATA[{record_field,LINE,Rep(A),Rep(E)}]]></c>.</item> - <item>If V is <c><![CDATA[A :: T]]></c>, where <c><![CDATA[A]]></c> is - an atom and <c><![CDATA[T]]></c> is a type and it does not contain - <c><![CDATA[undefined]]></c> syntactically, then Rep(V) = - <c><![CDATA[{typed_record_field,{record_field,LINE,Rep(A)},Rep(undefined | T)}]]></c>. - Note that if <![CDATA[T]]> is an annotated type, it will be wrapped in - parentheses.</item> - <item>If V is <c><![CDATA[A :: T]]></c>, where <c><![CDATA[A]]></c> is - an atom and <c><![CDATA[T]]></c> is a type, then Rep(V) = - <c><![CDATA[{typed_record_field,{record_field,LINE,Rep(A)},Rep(T)}]]></c>. - </item> - <item>If V is <c><![CDATA[A = E :: T]]></c>, where <c><![CDATA[A]]></c> - is an atom, <c><![CDATA[E]]></c> is an expression and - <c><![CDATA[T]]></c> is a type, then Rep(V) = - <c><![CDATA[{typed_record_field,{record_field,LINE,Rep(A),Rep(E)},Rep(T)}]]></c>. - </item> - </list> - </section> - - <section> - <title>Representation of parse errors and end of file</title> + <title>Representation of Parse Errors and End-of-file</title> <p>In addition to the representations of forms, the list that represents - a module declaration (as returned by functions in <c><![CDATA[erl_parse]]></c> and - <c><![CDATA[epp]]></c>) may contain tuples <c><![CDATA[{error,E}]]></c> and <c><![CDATA[{warning,W}]]></c>, denoting - syntactically incorrect forms and warnings, and <c><![CDATA[{eof,LINE}]]></c>, denoting an end - of stream encountered before a complete form had been parsed.</p> + a module declaration (as returned by functions in <c>erl_parse</c> and + <c>epp</c>) may contain tuples <c>{error,E}</c> and + <c>{warning,W}</c>, denoting syntactically incorrect forms and + warnings, and <c>{eof,LINE}</c>, denoting an end-of-stream + encountered before a complete form had been parsed.</p> </section> </section> <section> - <title>Atomic literals</title> + <title>Atomic Literals</title> <p>There are five kinds of atomic literals, which are represented in the same way in patterns, expressions and guards:</p> <list type="bulleted"> <item>If L is an integer or character literal, then - Rep(L) = <c><![CDATA[{integer,LINE,L}]]></c>.</item> + Rep(L) = <c>{integer,LINE,L}</c>.</item> <item>If L is a float literal, then - Rep(L) = <c><![CDATA[{float,LINE,L}]]></c>.</item> + Rep(L) = <c>{float,LINE,L}</c>.</item> <item>If L is a string literal consisting of the characters - <c><![CDATA[C_1]]></c>, ..., <c><![CDATA[C_k]]></c>, then - Rep(L) = <c><![CDATA[{string,LINE,[C_1, ..., C_k]}]]></c>.</item> + <c>C_1</c>, ..., <c>C_k</c>, then + Rep(L) = <c>{string,LINE,[C_1, ..., C_k]}</c>.</item> <item>If L is an atom literal, then - Rep(L) = <c><![CDATA[{atom,LINE,L}]]></c>.</item> + Rep(L) = <c>{atom,LINE,L}</c>.</item> </list> <p>Note that negative integer and float literals do not occur as such; they are parsed as an application of the unary negation operator.</p> @@ -295,47 +178,47 @@ <section> <title>Patterns</title> - <p>If <c><![CDATA[Ps]]></c> is a sequence of patterns <c><![CDATA[P_1, ..., P_k]]></c>, then - Rep(Ps) = <c><![CDATA[[Rep(P_1), ..., Rep(P_k)]]]></c>. Such sequences occur as the + <p>If <c>Ps</c> is a sequence of patterns <c>P_1, ..., P_k</c>, then + Rep(Ps) = <c>[Rep(P_1), ..., Rep(P_k)]</c>. Such sequences occur as the list of arguments to a function or fun.</p> <p>Individual patterns are represented as follows:</p> <list type="bulleted"> <item>If P is an atomic literal L, then Rep(P) = Rep(L).</item> - <item>If P is a compound pattern <c><![CDATA[P_1 = P_2]]></c>, then - Rep(P) = <c><![CDATA[{match,LINE,Rep(P_1),Rep(P_2)}]]></c>.</item> - <item>If P is a variable pattern <c><![CDATA[V]]></c>, then - Rep(P) = <c><![CDATA[{var,LINE,A}]]></c>, + <item>If P is a compound pattern <c>P_1 = P_2</c>, then + Rep(P) = <c>{match,LINE,Rep(P_1),Rep(P_2)}</c>.</item> + <item>If P is a variable pattern <c>V</c>, then + Rep(P) = <c>{var,LINE,A}</c>, where A is an atom with a printname consisting of the same characters as - <c><![CDATA[V]]></c>.</item> - <item>If P is a universal pattern <c><![CDATA[_]]></c>, then - Rep(P) = <c><![CDATA[{var,LINE,'_'}]]></c>.</item> - <item>If P is a tuple pattern <c><![CDATA[{P_1, ..., P_k}]]></c>, then - Rep(P) = <c><![CDATA[{tuple,LINE,[Rep(P_1), ..., Rep(P_k)]}]]></c>.</item> - <item>If P is a nil pattern <c><![CDATA[[]]]></c>, then - Rep(P) = <c><![CDATA[{nil,LINE}]]></c>.</item> - <item>If P is a cons pattern <c><![CDATA[[P_h | P_t]]]></c>, then - Rep(P) = <c><![CDATA[{cons,LINE,Rep(P_h),Rep(P_t)}]]></c>.</item> - <item>If E is a binary pattern <c><![CDATA[<<P_1:Size_1/TSL_1, ..., P_k:Size_k/TSL_k>>]]></c>, then - Rep(E) = <c><![CDATA[{bin,LINE,[{bin_element,LINE,Rep(P_1),Rep(Size_1),Rep(TSL_1)}, ..., {bin_element,LINE,Rep(P_k),Rep(Size_k),Rep(TSL_k)}]}]]></c>. + <c>V</c>.</item> + <item>If P is a universal pattern <c>_</c>, then + Rep(P) = <c>{var,LINE,'_'}</c>.</item> + <item>If P is a tuple pattern <c>{P_1, ..., P_k}</c>, then + Rep(P) = <c>{tuple,LINE,[Rep(P_1), ..., Rep(P_k)]}</c>.</item> + <item>If P is a nil pattern <c>[]</c>, then + Rep(P) = <c>{nil,LINE}</c>.</item> + <item>If P is a cons pattern <c>[P_h | P_t]</c>, then + Rep(P) = <c>{cons,LINE,Rep(P_h),Rep(P_t)}</c>.</item> + <item>If E is a binary pattern <c><<P_1:Size_1/TSL_1, ..., P_k:Size_k/TSL_k>></c>, then + Rep(E) = <c>{bin,LINE,[{bin_element,LINE,Rep(P_1),Rep(Size_1),Rep(TSL_1)}, ..., {bin_element,LINE,Rep(P_k),Rep(Size_k),Rep(TSL_k)}]}</c>. For Rep(TSL), see below. - An omitted <c><![CDATA[Size]]></c> is represented by <c><![CDATA[default]]></c>. An omitted <c><![CDATA[TSL]]></c> - (type specifier list) is represented by <c><![CDATA[default]]></c>.</item> - <item>If P is <c><![CDATA[P_1 Op P_2]]></c>, where <c><![CDATA[Op]]></c> is a binary operator (this - is either an occurrence of <c><![CDATA[++]]></c> applied to a literal string or character + An omitted <c>Size</c> is represented by <c>default</c>. An omitted <c>TSL</c> + (type specifier list) is represented by <c>default</c>.</item> + <item>If P is <c>P_1 Op P_2</c>, where <c>Op</c> is a binary operator (this + is either an occurrence of <c>++</c> applied to a literal string or character list, or an occurrence of an expression that can be evaluated to a number at compile time), - then Rep(P) = <c><![CDATA[{op,LINE,Op,Rep(P_1),Rep(P_2)}]]></c>.</item> - <item>If P is <c><![CDATA[Op P_0]]></c>, where <c><![CDATA[Op]]></c> is a unary operator (this is an + then Rep(P) = <c>{op,LINE,Op,Rep(P_1),Rep(P_2)}</c>.</item> + <item>If P is <c>Op P_0</c>, where <c>Op</c> is a unary operator (this is an occurrence of an expression that can be evaluated to a number at compile - time), then Rep(P) = <c><![CDATA[{op,LINE,Op,Rep(P_0)}]]></c>.</item> - <item>If P is a record pattern <c><![CDATA[#Name{Field_1=P_1, ..., Field_k=P_k}]]></c>, + time), then Rep(P) = <c>{op,LINE,Op,Rep(P_0)}</c>.</item> + <item>If P is a record pattern <c>#Name{Field_1=P_1, ..., Field_k=P_k}</c>, then Rep(P) = - <c><![CDATA[{record,LINE,Name, [{record_field,LINE,Rep(Field_1),Rep(P_1)}, ..., {record_field,LINE,Rep(Field_k),Rep(P_k)}]}]]></c>.</item> - <item>If P is <c><![CDATA[#Name.Field]]></c>, then - Rep(P) = <c><![CDATA[{record_index,LINE,Name,Rep(Field)}]]></c>.</item> - <item>If P is <c><![CDATA[( P_0 )]]></c>, then - Rep(P) = <c><![CDATA[Rep(P_0)]]></c>, - i.e., patterns cannot be distinguished from their bodies.</item> + <c>{record,LINE,Name,[{record_field,LINE,Rep(Field_1),Rep(P_1)}, ..., {record_field,LINE,Rep(Field_k),Rep(P_k)}]}</c>.</item> + <item>If P is <c>#Name.Field</c>, then + Rep(P) = <c>{record_index,LINE,Name,Rep(Field)}</c>.</item> + <item>If P is <c>( P_0 )</c>, then + Rep(P) = <c>Rep(P_0)</c>, + that is, patterns cannot be distinguished from their bodies.</item> </list> <p>Note that every pattern has the same source form as some expression, and is represented the same way as the corresponding expression.</p> @@ -343,180 +226,167 @@ <section> <title>Expressions</title> - <p>A body B is a sequence of expressions <c><![CDATA[E_1, ..., E_k]]></c>, and - Rep(B) = <c><![CDATA[[Rep(E_1), ..., Rep(E_k)]]]></c>.</p> + <p>A body B is a sequence of expressions <c>E_1, ..., E_k</c>, and + Rep(B) = <c>[Rep(E_1), ..., Rep(E_k)]</c>.</p> <p>An expression E is one of the following alternatives:</p> <list type="bulleted"> - <item>If P is an atomic literal <c><![CDATA[L]]></c>, then - Rep(P) = Rep(L).</item> - <item>If E is <c><![CDATA[P = E_0]]></c>, then - Rep(E) = <c><![CDATA[{match,LINE,Rep(P),Rep(E_0)}]]></c>.</item> - <item>If E is a variable <c><![CDATA[V]]></c>, then - Rep(E) = <c><![CDATA[{var,LINE,A}]]></c>, - where <c><![CDATA[A]]></c> is an atom with a printname consisting of the same - characters as <c><![CDATA[V]]></c>.</item> - <item>If E is a tuple skeleton <c><![CDATA[{E_1, ..., E_k}]]></c>, then - Rep(E) = <c><![CDATA[{tuple,LINE,[Rep(E_1), ..., Rep(E_k)]}]]></c>.</item> - <item>If E is <c><![CDATA[[]]]></c>, then - Rep(E) = <c><![CDATA[{nil,LINE}]]></c>.</item> - <item>If E is a cons skeleton <c><![CDATA[[E_h | E_t]]]></c>, then - Rep(E) = <c><![CDATA[{cons,LINE,Rep(E_h),Rep(E_t)}]]></c>.</item> - <item>If E is a binary constructor <c><![CDATA[<<V_1:Size_1/TSL_1, ..., V_k:Size_k/TSL_k>>]]></c>, then - Rep(E) = <c><![CDATA[{bin,LINE,[{bin_element,LINE,Rep(V_1),Rep(Size_1),Rep(TSL_1)}, ..., {bin_element,LINE,Rep(V_k),Rep(Size_k),Rep(TSL_k)}]}]]></c>. + <item>If P is an atomic literal <c>L</c>, then Rep(P) = Rep(L).</item> + <item>If E is <c>P = E_0</c>, then + Rep(E) = <c>{match,LINE,Rep(P),Rep(E_0)}</c>.</item> + <item>If E is a variable <c>V</c>, then Rep(E) = <c>{var,LINE,A}</c>, + where <c>A</c> is an atom with a printname consisting of the same + characters as <c>V</c>.</item> + <item>If E is a tuple skeleton <c>{E_1, ..., E_k}</c>, then + Rep(E) = <c>{tuple,LINE,[Rep(E_1), ..., Rep(E_k)]}</c>.</item> + <item>If E is <c>[]</c>, then + Rep(E) = <c>{nil,LINE}</c>.</item> + <item>If E is a cons skeleton <c>[E_h | E_t]</c>, then + Rep(E) = <c>{cons,LINE,Rep(E_h),Rep(E_t)}</c>.</item> + <item>If E is a binary constructor <c><<V_1:Size_1/TSL_1, ..., V_k:Size_k/TSL_k>></c>, then Rep(E) = + <c>{bin,LINE,[{bin_element,LINE,Rep(V_1),Rep(Size_1),Rep(TSL_1)}, ..., {bin_element,LINE,Rep(V_k),Rep(Size_k),Rep(TSL_k)}]}</c>. For Rep(TSL), see below. - An omitted <c><![CDATA[Size]]></c> is represented by <c><![CDATA[default]]></c>. An omitted <c><![CDATA[TSL]]></c> - (type specifier list) is represented by <c><![CDATA[default]]></c>.</item> - <item>If E is <c><![CDATA[E_1 Op E_2]]></c>, where <c><![CDATA[Op]]></c> is a binary operator, - then Rep(E) = <c><![CDATA[{op,LINE,Op,Rep(E_1),Rep(E_2)}]]></c>.</item> - <item>If E is <c><![CDATA[Op E_0]]></c>, where <c><![CDATA[Op]]></c> is a unary operator, then - Rep(E) = <c><![CDATA[{op,LINE,Op,Rep(E_0)}]]></c>.</item> - <item>If E is <c><![CDATA[#Name{Field_1=E_1, ..., Field_k=E_k}]]></c>, then - Rep(E) = - <c><![CDATA[{record,LINE,Name, [{record_field,LINE,Rep(Field_1),Rep(E_1)}, ..., {record_field,LINE,Rep(Field_k),Rep(E_k)}]}]]></c>.</item> - <item>If E is <c><![CDATA[E_0#Name{Field_1=E_1, ..., Field_k=E_k}]]></c>, then + An omitted <c>Size</c> is represented by <c>default</c>. An omitted <c>TSL</c> + (type specifier list) is represented by <c>default</c>.</item> + <item>If E is <c>E_1 Op E_2</c>, where <c>Op</c> is a binary operator, + then Rep(E) = <c>{op,LINE,Op,Rep(E_1),Rep(E_2)}</c>.</item> + <item>If E is <c>Op E_0</c>, where <c>Op</c> is a unary operator, then + Rep(E) = <c>{op,LINE,Op,Rep(E_0)}</c>.</item> + <item>If E is <c>#Name{Field_1=E_1, ..., Field_k=E_k}</c>, + then Rep(E) = + <c>{record,LINE,Name,[{record_field,LINE,Rep(Field_1),Rep(E_1)}, ..., {record_field,LINE,Rep(Field_k),Rep(E_k)}]}</c>.</item> + <item>If E is <c>E_0#Name{Field_1=E_1, ..., Field_k=E_k}</c>, then Rep(E) = - <c><![CDATA[{record,LINE,Rep(E_0),Name, [{record_field,LINE,Rep(Field_1),Rep(E_1)}, ..., {record_field,LINE,Rep(Field_k),Rep(E_k)}]}]]></c>.</item> - <item>If E is <c><![CDATA[#Name.Field]]></c>, then - Rep(E) = <c><![CDATA[{record_index,LINE,Name,Rep(Field)}]]></c>.</item> - <item>If E is <c><![CDATA[E_0#Name.Field]]></c>, then - Rep(E) = <c><![CDATA[{record_field,LINE,Rep(E_0),Name,Rep(Field)}]]></c>.</item> - <item>If E is <c><![CDATA[#{W_1, ..., W_k}]]></c> where each - <c><![CDATA[W_i]]></c> is a map assoc or exact field, then Rep(E) = - <c><![CDATA[{map,LINE,[Rep(W_1), ..., Rep(W_k)]}]]></c>. For Rep(W), see + <c>{record,LINE,Rep(E_0),Name,[{record_field,LINE,Rep(Field_1),Rep(E_1)}, ..., {record_field,LINE,Rep(Field_k),Rep(E_k)}]}</c>.</item> + <item>If E is <c>#Name.Field</c>, then + Rep(E) = <c>{record_index,LINE,Name,Rep(Field)}</c>.</item> + <item>If E is <c>E_0#Name.Field</c>, then + Rep(E) = <c>{record_field,LINE,Rep(E_0),Name,Rep(Field)}</c>.</item> + <item>If E is <c>#{W_1, ..., W_k}</c> where each + <c>W_i</c> is a map assoc or exact field, then Rep(E) = + <c>{map,LINE,[Rep(W_1), ..., Rep(W_k)]}</c>. For Rep(W), see below.</item> - <item>If E is <c><![CDATA[E_0#{W_1, ..., W_k}]]></c> where - <c><![CDATA[W_i]]></c> is a map assoc or exact field, then Rep(E) = - <c><![CDATA[{map,LINE,Rep(E_0),[Rep(W_1), ..., Rep(W_k)]}]]></c>. For - Rep(W), see below.</item> - <item>If E is <c><![CDATA[catch E_0]]></c>, then - Rep(E) = <c><![CDATA[{'catch',LINE,Rep(E_0)}]]></c>.</item> - <item>If E is <c><![CDATA[E_0(E_1, ..., E_k)]]></c>, then - Rep(E) = <c><![CDATA[{call,LINE,Rep(E_0),[Rep(E_1), ..., Rep(E_k)]}]]></c>.</item> - <item>If E is <c><![CDATA[E_m:E_0(E_1, ..., E_k)]]></c>, then - Rep(E) = - <c><![CDATA[{call,LINE,{remote,LINE,Rep(E_m),Rep(E_0)},[Rep(E_1), ..., Rep(E_k)]}]]></c>.</item> - <item>If E is a list comprehension <c><![CDATA[[E_0 || W_1, ..., W_k]]]></c>, - where each <c><![CDATA[W_i]]></c> is a generator or a filter, then - Rep(E) = <c><![CDATA[{lc,LINE,Rep(E_0),[Rep(W_1), ..., Rep(W_k)]}]]></c>. For Rep(W), see - below.</item> - <item>If E is a binary comprehension <c><![CDATA[<<E_0 || W_1, ..., W_k>>]]></c>, - where each <c><![CDATA[W_i]]></c> is a generator or a filter, then - Rep(E) = <c><![CDATA[{bc,LINE,Rep(E_0),[Rep(W_1), ..., Rep(W_k)]}]]></c>. For Rep(W), see + <item>If E is <c>E_0#{W_1, ..., W_k}</c> where + <c>W_i</c> is a map assoc or exact field, then Rep(E) = + <c>{map,LINE,Rep(E_0),[Rep(W_1), ..., Rep(W_k)]}</c>. + For Rep(W), see below.</item> + <item>If E is <c>catch E_0</c>, then + Rep(E) = <c>{'catch',LINE,Rep(E_0)}</c>.</item> + <item>If E is <c>E_0(E_1, ..., E_k)</c>, then + Rep(E) = <c>{call,LINE,Rep(E_0),[Rep(E_1), ..., Rep(E_k)]}</c>.</item> + <item>If E is <c>E_m:E_0(E_1, ..., E_k)</c>, then Rep(E) = + <c>{call,LINE,{remote,LINE,Rep(E_m),Rep(E_0)},[Rep(E_1), ..., Rep(E_k)]}</c>. + </item> + <item>If E is a list comprehension <c>[E_0 || W_1, ..., W_k]</c>, + where each <c>W_i</c> is a generator or a filter, then Rep(E) = + <c>{lc,LINE,Rep(E_0),[Rep(W_1), ..., Rep(W_k)]}</c>. For Rep(W), see below.</item> - <item>If E is <c><![CDATA[begin B end]]></c>, where <c><![CDATA[B]]></c> is a body, then - Rep(E) = <c><![CDATA[{block,LINE,Rep(B)}]]></c>.</item> - <item>If E is <c><![CDATA[if Ic_1 ; ... ; Ic_k end]]></c>, - where each <c><![CDATA[Ic_i]]></c> is an if clause then - Rep(E) = - <c><![CDATA[{'if',LINE,[Rep(Ic_1), ..., Rep(Ic_k)]}]]></c>.</item> - <item>If E is <c><![CDATA[case E_0 of Cc_1 ; ... ; Cc_k end]]></c>, - where <c><![CDATA[E_0]]></c> is an expression and each <c><![CDATA[Cc_i]]></c> is a - case clause then - Rep(E) = - <c><![CDATA[{'case',LINE,Rep(E_0),[Rep(Cc_1), ..., Rep(Cc_k)]}]]></c>.</item> - <item>If E is <c><![CDATA[try B catch Tc_1 ; ... ; Tc_k end]]></c>, - where <c><![CDATA[B]]></c> is a body and each <c><![CDATA[Tc_i]]></c> is a catch clause then - Rep(E) = - <c><![CDATA[{'try',LINE,Rep(B),[],[Rep(Tc_1), ..., Rep(Tc_k)],[]}]]></c>.</item> - <item>If E is <c><![CDATA[try B of Cc_1 ; ... ; Cc_k catch Tc_1 ; ... ; Tc_n end]]></c>, - where <c><![CDATA[B]]></c> is a body, - each <c><![CDATA[Cc_i]]></c> is a case clause and - each <c><![CDATA[Tc_j]]></c> is a catch clause then - Rep(E) = - <c><![CDATA[{'try',LINE,Rep(B),[Rep(Cc_1), ..., Rep(Cc_k)],[Rep(Tc_1), ..., Rep(Tc_n)],[]}]]></c>.</item> - <item>If E is <c><![CDATA[try B after A end]]></c>, - where <c><![CDATA[B]]></c> and <c><![CDATA[A]]></c> are bodies then - Rep(E) = - <c><![CDATA[{'try',LINE,Rep(B),[],[],Rep(A)}]]></c>.</item> - <item>If E is <c><![CDATA[try B of Cc_1 ; ... ; Cc_k after A end]]></c>, - where <c><![CDATA[B]]></c> and <c><![CDATA[A]]></c> are a bodies and - each <c><![CDATA[Cc_i]]></c> is a case clause then - Rep(E) = - <c><![CDATA[{'try',LINE,Rep(B),[Rep(Cc_1), ..., Rep(Cc_k)],[],Rep(A)}]]></c>.</item> - <item>If E is <c><![CDATA[try B catch Tc_1 ; ... ; Tc_k after A end]]></c>, - where <c><![CDATA[B]]></c> and <c><![CDATA[A]]></c> are bodies and - each <c><![CDATA[Tc_i]]></c> is a catch clause then - Rep(E) = - <c><![CDATA[{'try',LINE,Rep(B),[],[Rep(Tc_1), ..., Rep(Tc_k)],Rep(A)}]]></c>.</item> - <item>If E is <c><![CDATA[try B of Cc_1 ; ... ; Cc_k catch Tc_1 ; ... ; Tc_n after A end]]></c>, - where <c><![CDATA[B]]></c> and <c><![CDATA[A]]></c> are a bodies, - each <c><![CDATA[Cc_i]]></c> is a case clause and - each <c><![CDATA[Tc_j]]></c> is a catch clause then - Rep(E) = - <c><![CDATA[{'try',LINE,Rep(B),[Rep(Cc_1), ..., Rep(Cc_k)],[Rep(Tc_1), ..., Rep(Tc_n)],Rep(A)}]]></c>.</item> - <item>If E is <c><![CDATA[receive Cc_1 ; ... ; Cc_k end]]></c>, - where each <c><![CDATA[Cc_i]]></c> is a case clause then + <item>If E is a binary comprehension + <c><<E_0 || W_1, ..., W_k>></c>, + where each <c>W_i</c> is a generator or a filter, then + Rep(E) = <c>{bc,LINE,Rep(E_0),[Rep(W_1), ..., Rep(W_k)]}</c>. + For Rep(W), see below.</item> + <item>If E is <c>begin B end</c>, where <c>B</c> is a body, then + Rep(E) = <c>{block,LINE,Rep(B)}</c>.</item> + <item>If E is <c>if Ic_1 ; ... ; Ic_k end</c>, + where each <c>Ic_i</c> is an if clause then Rep(E) = + <c>{'if',LINE,[Rep(Ic_1), ..., Rep(Ic_k)]}</c>.</item> + <item>If E is <c>case E_0 of Cc_1 ; ... ; Cc_k end</c>, + where <c>E_0</c> is an expression and each <c>Cc_i</c> is a + case clause then Rep(E) = + <c>{'case',LINE,Rep(E_0),[Rep(Cc_1), ..., Rep(Cc_k)]}</c>.</item> + <item>If E is <c>try B catch Tc_1 ; ... ; Tc_k end</c>, + where <c>B</c> is a body and each <c>Tc_i</c> is a catch clause then Rep(E) = - <c><![CDATA[{'receive',LINE,[Rep(Cc_1), ..., Rep(Cc_k)]}]]></c>.</item> - <item>If E is <c><![CDATA[receive Cc_1 ; ... ; Cc_k after E_0 -> B_t end]]></c>, - where each <c><![CDATA[Cc_i]]></c> is a case clause, - <c><![CDATA[E_0]]></c> is an expression and <c><![CDATA[B_t]]></c> is a body, then + <c>{'try',LINE,Rep(B),[],[Rep(Tc_1), ..., Rep(Tc_k)],[]}</c>.</item> + <item>If E is <c>try B of Cc_1 ; ... ; Cc_k catch Tc_1 ; ... ; Tc_n end</c>, + where <c>B</c> is a body, + each <c>Cc_i</c> is a case clause and + each <c>Tc_j</c> is a catch clause then Rep(E) = + <c>{'try',LINE,Rep(B),[Rep(Cc_1), ..., Rep(Cc_k)],[Rep(Tc_1), ..., Rep(Tc_n)],[]}</c>.</item> + <item>If E is <c>try B after A end</c>, + where <c>B</c> and <c>A</c> are bodies then Rep(E) = + <c>{'try',LINE,Rep(B),[],[],Rep(A)}</c>.</item> + <item>If E is <c>try B of Cc_1 ; ... ; Cc_k after A end</c>, + where <c>B</c> and <c>A</c> are a bodies and + each <c>Cc_i</c> is a case clause then Rep(E) = + <c>{'try',LINE,Rep(B),[Rep(Cc_1), ..., Rep(Cc_k)],[],Rep(A)}</c>.</item> + <item>If E is <c>try B catch Tc_1 ; ... ; Tc_k after A end</c>, + where <c>B</c> and <c>A</c> are bodies and + each <c>Tc_i</c> is a catch clause then Rep(E) = + <c>{'try',LINE,Rep(B),[],[Rep(Tc_1), ..., Rep(Tc_k)],Rep(A)}</c>.</item> + <item>If E is <c>try B of Cc_1 ; ... ; Cc_k catch Tc_1 ; ... ; Tc_n after A end</c>, + where <c>B</c> and <c>A</c> are a bodies, + each <c>Cc_i</c> is a case clause and + each <c>Tc_j</c> is a catch clause then Rep(E) = - <c><![CDATA[{'receive',LINE,[Rep(Cc_1), ..., Rep(Cc_k)],Rep(E_0),Rep(B_t)}]]></c>.</item> - <item>If E is <c><![CDATA[fun Name / Arity]]></c>, then - Rep(E) = <c><![CDATA[{'fun',LINE,{function,Name,Arity}}]]></c>.</item> - <item>If E is <c><![CDATA[fun Module:Name/Arity]]></c>, then - Rep(E) = <c><![CDATA[{'fun',LINE,{function,Rep(Module),Rep(Name),Rep(Arity)}}]]></c>. - (Before the R15 release: Rep(E) = <c><![CDATA[{'fun',LINE,{function,Module,Name,Arity}}]]></c>.)</item> - <item>If E is <c><![CDATA[fun Fc_1 ; ... ; Fc_k end]]></c> - where each <c><![CDATA[Fc_i]]></c> is a function clause then Rep(E) = - <c><![CDATA[{'fun',LINE,{clauses,[Rep(Fc_1), ..., Rep(Fc_k)]}}]]></c>.</item> - <item>If E is <c><![CDATA[fun Name Fc_1 ; ... ; Name Fc_k end]]></c> - where <c><![CDATA[Name]]></c> is a variable and each - <c><![CDATA[Fc_i]]></c> is a function clause then Rep(E) = - <c><![CDATA[{named_fun,LINE,Name,[Rep(Fc_1), ..., Rep(Fc_k)]}]]></c>. + <c>{'try',LINE,Rep(B),[Rep(Cc_1), ..., Rep(Cc_k)],[Rep(Tc_1), ..., Rep(Tc_n)],Rep(A)}</c>.</item> + <item>If E is <c>receive Cc_1 ; ... ; Cc_k end</c>, + where each <c>Cc_i</c> is a case clause then Rep(E) = + <c>{'receive',LINE,[Rep(Cc_1), ..., Rep(Cc_k)]}</c>.</item> + <item>If E is <c>receive Cc_1 ; ... ; Cc_k after E_0 -> B_t end</c>, + where each <c>Cc_i</c> is a case clause, + <c>E_0</c> is an expression and <c>B_t</c> is a body, then Rep(E) = + <c>{'receive',LINE,[Rep(Cc_1), ..., Rep(Cc_k)],Rep(E_0),Rep(B_t)}</c>.</item> + <item>If E is <c>fun Name / Arity</c>, then + Rep(E) = <c>{'fun',LINE,{function,Name,Arity}}</c>.</item> + <item>If E is <c>fun Module:Name/Arity</c>, then Rep(E) = + <c>{'fun',LINE,{function,Rep(Module),Rep(Name),Rep(Arity)}}</c>. + (Before the R15 release: Rep(E) = + <c>{'fun',LINE,{function,Module,Name,Arity}}</c>.)</item> + <item>If E is <c>fun Fc_1 ; ... ; Fc_k end</c> + where each <c>Fc_i</c> is a function clause then Rep(E) = + <c>{'fun',LINE,{clauses,[Rep(Fc_1), ..., Rep(Fc_k)]}}</c>.</item> + <item>If E is <c>fun Name Fc_1 ; ... ; Name Fc_k end</c> + where <c>Name</c> is a variable and each + <c>Fc_i</c> is a function clause then Rep(E) = + <c>{named_fun,LINE,Name,[Rep(Fc_1), ..., Rep(Fc_k)]}</c>. </item> - <item>If E is <c><![CDATA[query [E_0 || W_1, ..., W_k] end]]></c>, - where each <c><![CDATA[W_i]]></c> is a generator or a filter, then - Rep(E) = <c><![CDATA[{'query',LINE,{lc,LINE,Rep(E_0),[Rep(W_1), ..., Rep(W_k)]}}]]></c>. - For Rep(W), see below.</item> - <item>If E is <c><![CDATA[E_0.Field]]></c>, a Mnesia record access - inside a query, then - Rep(E) = <c><![CDATA[{record_field,LINE,Rep(E_0),Rep(Field)}]]></c>.</item> - <item>If E is <c><![CDATA[( E_0 )]]></c>, then - Rep(E) = <c><![CDATA[Rep(E_0)]]></c>, - i.e., parenthesized expressions cannot be distinguished from their bodies.</item> + <item>If E is <c>( E_0 )</c>, then + Rep(E) = <c>Rep(E_0)</c>, that is, parenthesized + expressions cannot be distinguished from their bodies.</item> </list> <section> - <title>Generators and filters</title> - <p>When W is a generator or a filter (in the body of a list or binary comprehension), then:</p> + <title>Generators and Filters</title> + <p>When W is a generator or a filter (in the body of a list or + binary comprehension), then:</p> <list type="bulleted"> - <item>If W is a generator <c><![CDATA[P <- E]]></c>, where <c><![CDATA[P]]></c> is a pattern and <c><![CDATA[E]]></c> - is an expression, then - Rep(W) = <c><![CDATA[{generate,LINE,Rep(P),Rep(E)}]]></c>.</item> - <item>If W is a generator <c><![CDATA[P <= E]]></c>, where <c><![CDATA[P]]></c> is a pattern and <c><![CDATA[E]]></c> - is an expression, then - Rep(W) = <c><![CDATA[{b_generate,LINE,Rep(P),Rep(E)}]]></c>.</item> - <item>If W is a filter <c><![CDATA[E]]></c>, which is an expression, then - Rep(W) = <c><![CDATA[Rep(E)]]></c>.</item> + <item>If W is a generator <c>P <- E</c>, where <c>P</c> is + a pattern and <c>E</c> is an expression, then + Rep(W) = <c>{generate,LINE,Rep(P),Rep(E)}</c>.</item> + <item>If W is a generator <c>P <= E</c>, where <c>P</c> is + a pattern and <c>E</c> is an expression, then + Rep(W) = <c>{b_generate,LINE,Rep(P),Rep(E)}</c>.</item> + <item>If W is a filter <c>E</c>, which is an expression, then + Rep(W) = <c>Rep(E)</c>.</item> </list> </section> <section> - <title>Binary element type specifiers</title> + <title>Binary Element Type Specifiers</title> <p>A type specifier list TSL for a binary element is a sequence of type - specifiers <c><![CDATA[TS_1 - ... - TS_k]]></c>. - Rep(TSL) = <c><![CDATA[[Rep(TS_1), ..., Rep(TS_k)]]]></c>.</p> + specifiers <c>TS_1 - ... - TS_k</c>. + Rep(TSL) = <c>[Rep(TS_1), ..., Rep(TS_k)]</c>.</p> <p>When TS is a type specifier for a binary element, then:</p> <list type="bulleted"> - <item>If TS is an atom <c><![CDATA[A]]></c>, Rep(TS) = <c><![CDATA[A]]></c>.</item> - <item>If TS is a couple <c><![CDATA[A:Value]]></c> where <c><![CDATA[A]]></c> is an atom and <c><![CDATA[Value]]></c> - is an integer, Rep(TS) = <c><![CDATA[{A, Value}]]></c>.</item> + <item>If TS is an atom <c>A</c>, then Rep(TS) = <c>A</c>.</item> + <item>If TS is a couple <c>A:Value</c> where <c>A</c> is an atom + and <c>Value</c> is an integer, then Rep(TS) = + <c>{A,Value}</c>.</item> </list> </section> <section> - <title>Map assoc and exact fields</title> + <title>Map Assoc and Exact Fields</title> <p>When W is an assoc or exact field (in the body of a map), then:</p> <list type="bulleted"> - <item>If W is an assoc field <c><![CDATA[K => V]]></c>, where - <c><![CDATA[K]]></c> and <c><![CDATA[V]]></c> are both expressions, - then Rep(W) = <c><![CDATA[{map_field_assoc,LINE,Rep(K),Rep(V)}]]></c>. + <item>If W is an assoc field <c>K => V</c>, where + <c>K</c> and <c>V</c> are both expressions, + then Rep(W) = <c>{map_field_assoc,LINE,Rep(K),Rep(V)}</c>. </item> - <item>If W is an exact field <c><![CDATA[K := V]]></c>, where - <c><![CDATA[K]]></c> and <c><![CDATA[V]]></c> are both expressions, - then Rep(W) = <c><![CDATA[{map_field_exact,LINE,Rep(K),Rep(V)}]]></c>. + <item>If W is an exact field <c>K := V</c>, where + <c>K</c> and <c>V</c> are both expressions, + then Rep(W) = <c>{map_field_exact,LINE,Rep(K),Rep(V)}</c>. </item> </list> </section> @@ -524,112 +394,220 @@ <section> <title>Clauses</title> - <p>There are function clauses, if clauses, case clauses + <p>There are function clauses, if clauses, case clauses and catch clauses.</p> - <p>A clause <c><![CDATA[C]]></c> is one of the following alternatives:</p> + <p>A clause <c>C</c> is one of the following alternatives:</p> <list type="bulleted"> - <item>If C is a function clause <c><![CDATA[( Ps ) -> B]]></c> - where <c><![CDATA[Ps]]></c> is a pattern sequence and <c><![CDATA[B]]></c> is a body, then - Rep(C) = <c><![CDATA[{clause,LINE,Rep(Ps),[],Rep(B)}]]></c>.</item> - <item>If C is a function clause <c><![CDATA[( Ps ) when Gs -> B]]></c> - where <c><![CDATA[Ps]]></c> is a pattern sequence, - <c><![CDATA[Gs]]></c> is a guard sequence and <c><![CDATA[B]]></c> is a body, then - Rep(C) = <c><![CDATA[{clause,LINE,Rep(Ps),Rep(Gs),Rep(B)}]]></c>.</item> - <item>If C is an if clause <c><![CDATA[Gs -> B]]></c> - where <c><![CDATA[Gs]]></c> is a guard sequence and <c><![CDATA[B]]></c> is a body, then - Rep(C) = <c><![CDATA[{clause,LINE,[],Rep(Gs),Rep(B)}]]></c>.</item> - <item>If C is a case clause <c><![CDATA[P -> B]]></c> - where <c><![CDATA[P]]></c> is a pattern and <c><![CDATA[B]]></c> is a body, then - Rep(C) = <c><![CDATA[{clause,LINE,[Rep(P)],[],Rep(B)}]]></c>.</item> - <item>If C is a case clause <c><![CDATA[P when Gs -> B]]></c> - where <c><![CDATA[P]]></c> is a pattern, - <c><![CDATA[Gs]]></c> is a guard sequence and <c><![CDATA[B]]></c> is a body, then - Rep(C) = <c><![CDATA[{clause,LINE,[Rep(P)],Rep(Gs),Rep(B)}]]></c>.</item> - <item>If C is a catch clause <c><![CDATA[P -> B]]></c> - where <c><![CDATA[P]]></c> is a pattern and <c><![CDATA[B]]></c> is a body, then - Rep(C) = <c><![CDATA[{clause,LINE,[Rep({throw,P,_})],[],Rep(B)}]]></c>.</item> - <item>If C is a catch clause <c><![CDATA[X : P -> B]]></c> - where <c><![CDATA[X]]></c> is an atomic literal or a variable pattern, - <c><![CDATA[P]]></c> is a pattern and <c><![CDATA[B]]></c> is a body, then - Rep(C) = <c><![CDATA[{clause,LINE,[Rep({X,P,_})],[],Rep(B)}]]></c>.</item> - <item>If C is a catch clause <c><![CDATA[P when Gs -> B]]></c> - where <c><![CDATA[P]]></c> is a pattern, <c><![CDATA[Gs]]></c> is a guard sequence - and <c><![CDATA[B]]></c> is a body, then - Rep(C) = <c><![CDATA[{clause,LINE,[Rep({throw,P,_})],Rep(Gs),Rep(B)}]]></c>.</item> - <item>If C is a catch clause <c><![CDATA[X : P when Gs -> B]]></c> - where <c><![CDATA[X]]></c> is an atomic literal or a variable pattern, - <c><![CDATA[P]]></c> is a pattern, <c><![CDATA[Gs]]></c> is a guard sequence - and <c><![CDATA[B]]></c> is a body, then - Rep(C) = <c><![CDATA[{clause,LINE,[Rep({X,P,_})],Rep(Gs),Rep(B)}]]></c>.</item> + <item>If C is a function clause <c>( Ps ) -> B</c> + where <c>Ps</c> is a pattern sequence and <c>B</c> is a body, then + Rep(C) = <c>{clause,LINE,Rep(Ps),[],Rep(B)}</c>.</item> + <item>If C is a function clause <c>( Ps ) when Gs -> B</c> + where <c>Ps</c> is a pattern sequence, + <c>Gs</c> is a guard sequence and <c>B</c> is a body, then + Rep(C) = <c>{clause,LINE,Rep(Ps),Rep(Gs),Rep(B)}</c>.</item> + <item>If C is an if clause <c>Gs -> B</c> + where <c>Gs</c> is a guard sequence and <c>B</c> is a body, then + Rep(C) = <c>{clause,LINE,[],Rep(Gs),Rep(B)}</c>.</item> + <item>If C is a case clause <c>P -> B</c> + where <c>P</c> is a pattern and <c>B</c> is a body, then + Rep(C) = <c>{clause,LINE,[Rep(P)],[],Rep(B)}</c>.</item> + <item>If C is a case clause <c>P when Gs -> B</c> + where <c>P</c> is a pattern, + <c>Gs</c> is a guard sequence and <c>B</c> is a body, then + Rep(C) = <c>{clause,LINE,[Rep(P)],Rep(Gs),Rep(B)}</c>.</item> + <item>If C is a catch clause <c>P -> B</c> + where <c>P</c> is a pattern and <c>B</c> is a body, then + Rep(C) = <c>{clause,LINE,[Rep({throw,P,_})],[],Rep(B)}</c>.</item> + <item>If C is a catch clause <c>X : P -> B</c> + where <c>X</c> is an atomic literal or a variable pattern, + <c>P</c> is a pattern and <c>B</c> is a body, then + Rep(C) = <c>{clause,LINE,[Rep({X,P,_})],[],Rep(B)}</c>.</item> + <item>If C is a catch clause <c>P when Gs -> B</c> + where <c>P</c> is a pattern, <c>Gs</c> is a guard sequence + and <c>B</c> is a body, then + Rep(C) = <c>{clause,LINE,[Rep({throw,P,_})],Rep(Gs),Rep(B)}</c>.</item> + <item>If C is a catch clause <c>X : P when Gs -> B</c> + where <c>X</c> is an atomic literal or a variable pattern, + <c>P</c> is a pattern, <c>Gs</c> is a guard sequence + and <c>B</c> is a body, then + Rep(C) = <c>{clause,LINE,[Rep({X,P,_})],Rep(Gs),Rep(B)}</c>.</item> </list> </section> <section> <title>Guards</title> - <p>A guard sequence Gs is a sequence of guards <c><![CDATA[G_1; ...; G_k]]></c>, and - Rep(Gs) = <c><![CDATA[[Rep(G_1), ..., Rep(G_k)]]]></c>. If the guard sequence is - empty, Rep(Gs) = <c><![CDATA[[]]]></c>.</p> - <p>A guard G is a nonempty sequence of guard tests <c><![CDATA[Gt_1, ..., Gt_k]]></c>, and - Rep(G) = <c><![CDATA[[Rep(Gt_1), ..., Rep(Gt_k)]]]></c>.</p> - <p>A guard test <c><![CDATA[Gt]]></c> is one of the following alternatives:</p> + <p>A guard sequence Gs is a sequence of guards <c>G_1; ...; G_k</c>, and + Rep(Gs) = <c>[Rep(G_1), ..., Rep(G_k)]</c>. If the guard sequence is + empty, Rep(Gs) = <c>[]</c>.</p> + <p>A guard G is a nonempty sequence of guard tests + <c>Gt_1, ..., Gt_k</c>, and Rep(G) = + <c>[Rep(Gt_1), ..., Rep(Gt_k)]</c>.</p> + <p>A guard test <c>Gt</c> is one of the following alternatives:</p> <list type="bulleted"> <item>If Gt is an atomic literal L, then Rep(Gt) = Rep(L).</item> - <item>If Gt is a variable pattern <c><![CDATA[V]]></c>, then - Rep(Gt) = <c><![CDATA[{var,LINE,A}]]></c>, - where A is an atom with a printname consisting of the same characters as - <c><![CDATA[V]]></c>.</item> - <item>If Gt is a tuple skeleton <c><![CDATA[{Gt_1, ..., Gt_k}]]></c>, then - Rep(Gt) = <c><![CDATA[{tuple,LINE,[Rep(Gt_1), ..., Rep(Gt_k)]}]]></c>.</item> - <item>If Gt is <c><![CDATA[[]]]></c>, then - Rep(Gt) = <c><![CDATA[{nil,LINE}]]></c>.</item> - <item>If Gt is a cons skeleton <c><![CDATA[[Gt_h | Gt_t]]]></c>, then - Rep(Gt) = <c><![CDATA[{cons,LINE,Rep(Gt_h),Rep(Gt_t)}]]></c>.</item> - <item>If Gt is a binary constructor <c><![CDATA[<<Gt_1:Size_1/TSL_1, ..., Gt_k:Size_k/TSL_k>>]]></c>, then - Rep(Gt) = <c><![CDATA[{bin,LINE,[{bin_element,LINE,Rep(Gt_1),Rep(Size_1),Rep(TSL_1)}, ..., {bin_element,LINE,Rep(Gt_k),Rep(Size_k),Rep(TSL_k)}]}]]></c>. + <item>If Gt is a variable pattern <c>V</c>, then + Rep(Gt) = <c>{var,LINE,A}</c>, where A is an atom with + a printname consisting of the same characters as <c>V</c>.</item> + <item>If Gt is a tuple skeleton <c>{Gt_1, ..., Gt_k}</c>, then + Rep(Gt) = <c>{tuple,LINE,[Rep(Gt_1), ..., Rep(Gt_k)]}</c>.</item> + <item>If Gt is <c>[]</c>, then Rep(Gt) = <c>{nil,LINE}</c>.</item> + <item>If Gt is a cons skeleton <c>[Gt_h | Gt_t]</c>, then + Rep(Gt) = <c>{cons,LINE,Rep(Gt_h),Rep(Gt_t)}</c>.</item> + <item>If Gt is a binary constructor + <c><<Gt_1:Size_1/TSL_1, ..., Gt_k:Size_k/TSL_k>></c>, then + Rep(Gt) = <c>{bin,LINE,[{bin_element,LINE,Rep(Gt_1),Rep(Size_1),Rep(TSL_1)}, ..., {bin_element,LINE,Rep(Gt_k),Rep(Size_k),Rep(TSL_k)}]}</c>. For Rep(TSL), see above. - An omitted <c><![CDATA[Size]]></c> is represented by <c><![CDATA[default]]></c>. An omitted <c><![CDATA[TSL]]></c> - (type specifier list) is represented by <c><![CDATA[default]]></c>.</item> - <item>If Gt is <c><![CDATA[Gt_1 Op Gt_2]]></c>, where <c><![CDATA[Op]]></c> - is a binary operator, then Rep(Gt) = <c><![CDATA[{op,LINE,Op,Rep(Gt_1),Rep(Gt_2)}]]></c>.</item> - <item>If Gt is <c><![CDATA[Op Gt_0]]></c>, where <c><![CDATA[Op]]></c> is a unary operator, then - Rep(Gt) = <c><![CDATA[{op,LINE,Op,Rep(Gt_0)}]]></c>.</item> - <item>If Gt is <c><![CDATA[#Name{Field_1=Gt_1, ..., Field_k=Gt_k}]]></c>, then + An omitted <c>Size</c> is represented by <c>default</c>. + An omitted <c>TSL</c> (type specifier list) is represented + by <c>default</c>.</item> + <item>If Gt is <c>Gt_1 Op Gt_2</c>, where <c>Op</c> + is a binary operator, then Rep(Gt) = + <c>{op,LINE,Op,Rep(Gt_1),Rep(Gt_2)}</c>.</item> + <item>If Gt is <c>Op Gt_0</c>, where <c>Op</c> is a unary operator, then + Rep(Gt) = <c>{op,LINE,Op,Rep(Gt_0)}</c>.</item> + <item>If Gt is <c>#Name{Field_1=Gt_1, ..., Field_k=Gt_k}</c>, then Rep(E) = - <c><![CDATA[{record,LINE,Name, [{record_field,LINE,Rep(Field_1),Rep(Gt_1)}, ..., {record_field,LINE,Rep(Field_k),Rep(Gt_k)}]}]]></c>.</item> - <item>If Gt is <c><![CDATA[#Name.Field]]></c>, then - Rep(Gt) = <c><![CDATA[{record_index,LINE,Name,Rep(Field)}]]></c>.</item> - <item>If Gt is <c><![CDATA[Gt_0#Name.Field]]></c>, then - Rep(Gt) = <c><![CDATA[{record_field,LINE,Rep(Gt_0),Name,Rep(Field)}]]></c>.</item> - <item>If Gt is <c><![CDATA[A(Gt_1, ..., Gt_k)]]></c>, where <c><![CDATA[A]]></c> is an atom, then - Rep(Gt) = <c><![CDATA[{call,LINE,Rep(A),[Rep(Gt_1), ..., Rep(Gt_k)]}]]></c>.</item> - <item>If Gt is <c><![CDATA[A_m:A(Gt_1, ..., Gt_k)]]></c>, where <c><![CDATA[A_m]]></c> is - the atom <c><![CDATA[erlang]]></c> and <c><![CDATA[A]]></c> is an atom or an operator, then - Rep(Gt) = <c><![CDATA[{call,LINE,{remote,LINE,Rep(A_m),Rep(A)},[Rep(Gt_1), ..., Rep(Gt_k)]}]]></c>.</item> - <item>If Gt is <c><![CDATA[{A_m,A}(Gt_1, ..., Gt_k)]]></c>, where <c><![CDATA[A_m]]></c> is - the atom <c><![CDATA[erlang]]></c> and <c><![CDATA[A]]></c> is an atom or an operator, then - Rep(Gt) = <c><![CDATA[{call,LINE,Rep({A_m,A}),[Rep(Gt_1), ..., Rep(Gt_k)]}]]></c>.</item> - <item>If Gt is <c><![CDATA[( Gt_0 )]]></c>, then - Rep(Gt) = <c><![CDATA[Rep(Gt_0)]]></c>, - i.e., parenthesized guard tests cannot be distinguished from their bodies.</item> + <c>{record,LINE,Name,[{record_field,LINE,Rep(Field_1),Rep(Gt_1)}, ..., {record_field,LINE,Rep(Field_k),Rep(Gt_k)}]}</c>.</item> + <item>If Gt is <c>#Name.Field</c>, then + Rep(Gt) = <c>{record_index,LINE,Name,Rep(Field)}</c>.</item> + <item>If Gt is <c>Gt_0#Name.Field</c>, then + Rep(Gt) = <c>{record_field,LINE,Rep(Gt_0),Name,Rep(Field)}</c>.</item> + <item>If Gt is <c>A(Gt_1, ..., Gt_k)</c>, where <c>A</c> is an atom, then + Rep(Gt) = <c>{call,LINE,Rep(A),[Rep(Gt_1), ..., Rep(Gt_k)]}</c>.</item> + <item>If Gt is <c>A_m:A(Gt_1, ..., Gt_k)</c>, where <c>A_m</c> is + the atom <c>erlang</c> and <c>A</c> is an atom or an operator, then + Rep(Gt) = <c>{call,LINE,{remote,LINE,Rep(A_m),Rep(A)},[Rep(Gt_1), ..., Rep(Gt_k)]}</c>.</item> + <item>If Gt is <c>{A_m,A}(Gt_1, ..., Gt_k)</c>, where <c>A_m</c> is + the atom <c>erlang</c> and <c>A</c> is an atom or an operator, then + Rep(Gt) = <c>{call,LINE,Rep({A_m,A}),[Rep(Gt_1), ..., Rep(Gt_k)]}</c>. + </item> + <item>If Gt is <c>( Gt_0 )</c>, then + Rep(Gt) = <c>Rep(Gt_0)</c>, that is, parenthesized + guard tests cannot be distinguished from their bodies.</item> </list> <p>Note that every guard test has the same source form as some expression, and is represented the same way as the corresponding expression.</p> </section> <section> - <title>The abstract format after preprocessing</title> - <p>The compilation option <c><![CDATA[debug_info]]></c> can be given to the - compiler to have the abstract code stored in - the <c><![CDATA[abstract_code]]></c> chunk in the BEAM file + <title>Types</title> + <list type="bulleted"> + <item>If T is an annotated type <c>Anno :: Type</c>, + where <c>Anno</c> is a variable and + <c>Type</c> is a type, then Rep(T) = + <c>{ann_type,LINE,[Rep(Anno),Rep(Type)]}</c>.</item> + <item>If T is an atom or integer literal L, then Rep(T) = Rep(L). + </item> + <item>If T is <c>L Op R</c>, + where <c>Op</c> is a binary operator and <c>L</c> and <c>R</c> + are types (this is an occurrence of an expression that can be + evaluated to an integer at compile time), then + Rep(T) = <c>{op,LINE,Op,Rep(L),Rep(R)}</c>.</item> + <item>If T is <c>Op A</c>, where <c>Op</c> is a + unary operator and <c>A</c> is a type (this is an occurrence of + an expression that can be evaluated to an integer at compile time), + then Rep(T) = <c>{op,LINE,Op,Rep(A)}</c>.</item> + <item>If T is a bitstring type <c><<_:M,_:_*N>></c>, + where <c>M</c> and <c>N</c> are singleton integer types, then Rep(T) = + <c>{type,LINE,binary,[Rep(M),Rep(N)]}</c>.</item> + <item>If T is the empty list type <c>[]</c>, then Rep(T) = + <c>{type,Line,nil,[]}</c>.</item> + <item>If T is a fun type <c>fun()</c>, then Rep(T) = + <c>{type,LINE,'fun',[]}</c>.</item> + <item>If T is a fun type <c>fun((...) -> B)</c>, + where <c>B</c> is a type, then + Rep(T) = <c>{type,LINE,'fun',[{type,LINE,any},Rep(B)]}</c>. + </item> + <item>If T is a fun type <c>fun(Ft)</c>, where + <c>Ft</c> is a function type, + then Rep(T) = <c>Rep(Ft)</c>.</item> + <item>If T is an integer range type <c>L .. H</c>, + where <c>L</c> and <c>H</c> are singleton integer types, then + Rep(T) = <c>{type,LINE,range,[Rep(L),Rep(H)]}</c>.</item> + <item>If T is a map type <c>map()</c>, then Rep(T) = + <c>{type,LINE,map,any}</c>.</item> + <item>If T is a map type <c>#{P_1, ..., P_k}</c>, where each + <c>P_i</c> is a map pair type, then Rep(T) = + <c>{type,LINE,map,[Rep(P_1), ..., Rep(P_k)]}</c>.</item> + <item>If T is a map pair type <c>K => V</c>, where + <c>K</c> and <c>V</c> are types, then Rep(T) = + <c>{type,LINE,map_field_assoc,[Rep(K),Rep(V)]}</c>.</item> + <item>If T is a predefined (or built-in) type <c>N(A_1, ..., A_k)</c>, + where each <c>A_i</c> is a type, then Rep(T) = + <c>{type,LINE,N,[Rep(A_1), ..., Rep(A_k)]}</c>.</item> + <item>If T is a record type <c>#Name{F_1, ..., F_k}</c>, + where each <c>F_i</c> is a record field type, then Rep(T) = + <c>{type,LINE,record,[Rep(Name),Rep(F_1), ..., Rep(F_k)]}</c>. + </item> + <item>If T is a record field type <c>Name :: Type</c>, + where <c>Type</c> is a type, then Rep(T) = + <c>{type,LINE,field_type,[Rep(Name),Rep(Type)]}</c>.</item> + <item>If T is a remote type <c>M:N(A_1, ..., A_k)</c>, where + each <c>A_i</c> is a type, then Rep(T) = + <c>{remote_type,LINE,[Rep(M),Rep(N),[Rep(A_1), ..., Rep(A_k)]]}</c>. + </item> + <item>If T is a tuple type <c>tuple()</c>, then Rep(T) = + <c>{type,LINE,tuple,any}</c>.</item> + <item>If T is a tuple type <c>{A_1, ..., A_k}</c>, where + each <c>A_i</c> is a type, then Rep(T) = + <c>{type,LINE,tuple,[Rep(A_1), ..., Rep(A_k)]}</c>.</item> + <item>If T is a type union <c>T_1 | ... | T_k</c>, + where each <c>T_i</c> is a type, then Rep(T) = + <c>{type,LINE,union,[Rep(T_1), ..., Rep(T_k)]}</c>.</item> + <item>If T is a type variable <c>V</c>, then Rep(T) = + <c>{var,LINE,A}</c>, where <c>A</c> is an atom with a printname + consisting of the same characters as <c>V</c>. A type variable + is any variable except underscore (<c>_</c>).</item> + <item>If T is a user-defined type <c>N(A_1, ..., A_k)</c>, + where each <c>A_i</c> is a type, then Rep(T) = + <c>{user_type,LINE,N,[Rep(A_1), ..., Rep(A_k)]}</c>.</item> + <item>If T is <c>( T_0 )</c>, then Rep(T) = <c>Rep(T_0)</c>, + that is, parenthesized types cannot be distinguished from their + bodies.</item> + </list> + + <section> + <title>Function Types</title> + <list type="bulleted"> + <item>If Ft is a constrained function type <c>Ft_1 when Fc</c>, + where <c>Ft_1</c> is a function type and + <c>Fc</c> is a function constraint, then Rep(T) = + <c>{type,LINE,bounded_fun,[Rep(Ft_1),Rep(Fc)]}</c>.</item> + <item>If Ft is a function type <c>(A_1, ..., A_n) -> B</c>, + where each <c>A_i</c> and <c>B</c> are types, then + Rep(Ft) = <c>{type,LINE,'fun',[{type,LINE,product,[Rep(A_1), + ..., Rep(A_n)]},Rep(B)]}</c>.</item> + </list> + </section> + + <section> + <title>Function Constraints</title> + <p>A function constraint Fc is a nonempty sequence of constraints + <c>C_1, ..., C_k</c>, and + Rep(Fc) = <c>[Rep(C_1), ..., Rep(C_k)]</c>.</p> + <list type="bulleted"> + <item>If C is a constraint <c>is_subtype(V, T)</c> or <c>V :: T</c>, + where <c>V</c> is a type variable and <c>T</c> is a type, then + Rep(C) = <c>{type,LINE,constraint,[Rep(F),[Rep(V),Rep(T)]]}</c>. + </item> + </list> + </section> + </section> + + <section> + <title>The Abstract Format After Preprocessing</title> + <p>The compilation option <c>debug_info</c> can be given to the + compiler to have the abstract code stored in + the <c>abstract_code</c> chunk in the BEAM file (for debugging purposes).</p> - <p>In OTP R9C and later, the <c><![CDATA[abstract_code]]></c> chunk will + <p>In OTP R9C and later, the <c>abstract_code</c> chunk will contain</p> - <p><c><![CDATA[{raw_abstract_v1,AbstractCode}]]></c></p> - <p>where <c><![CDATA[AbstractCode]]></c> is the abstract code as described + <p><c>{raw_abstract_v1,AbstractCode}</c></p> + <p>where <c>AbstractCode</c> is the abstract code as described in this document.</p> <p>In releases of OTP prior to R9C, the abstract code after some more processing was stored in the BEAM file. The first element of the - tuple would be either <c><![CDATA[abstract_v1]]></c> (R7B) or <c><![CDATA[abstract_v2]]></c> + tuple would be either <c>abstract_v1</c> (R7B) or <c>abstract_v2</c> (R8B).</p> </section> </chapter> diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index 42b6a3bfef..e717fc0c4e 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -2811,7 +2811,7 @@ ERL_DRV_MAP int sz </func> <func> - <name><ret>int</ret><nametext>erl_drv_putenv(char *key, char *value)</nametext></name> + <name><ret>int</ret><nametext>erl_drv_putenv(const char *key, char *value)</nametext></name> <fsummary>Set the value of an environment variable</fsummary> <desc> <marker id="erl_drv_putenv"></marker> @@ -2840,7 +2840,7 @@ ERL_DRV_MAP int sz </desc> </func> <func> - <name><ret>int</ret><nametext>erl_drv_getenv(char *key, char *value, size_t *value_size)</nametext></name> + <name><ret>int</ret><nametext>erl_drv_getenv(const char *key, char *value, size_t *value_size)</nametext></name> <fsummary>Get the value of an environment variable</fsummary> <desc> <marker id="erl_drv_getenv"></marker> diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index dae14b8d08..2d8706169f 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -791,6 +791,10 @@ typedef enum { and return true, or return false if <c>term</c> is not an unsigned integer or is outside the bounds of type <c>unsigned long</c>.</p></desc> </func> + <func><name><ret>int</ret><nametext>enif_getenv(const char* key, char* value, size_t *value_size)</nametext></name> + <fsummary>Get the value of an environment variable</fsummary> + <desc><p>Same as <seealso marker="erl_driver#erl_drv_getenv">erl_drv_getenv</seealso>.</p></desc> + </func> <func><name><ret>int</ret><nametext>enif_has_pending_exception(ErlNifEnv* env, ERL_NIF_TERM* reason)</nametext></name> <fsummary>Check if an exception has been raised</fsummary> <desc><p>Return true if a pending exception is associated diff --git a/erts/doc/src/erl_prim_loader.xml b/erts/doc/src/erl_prim_loader.xml index d05f0d9aea..db4f132609 100644 --- a/erts/doc/src/erl_prim_loader.xml +++ b/erts/doc/src/erl_prim_loader.xml @@ -36,17 +36,11 @@ the system. The start script is also fetched with this low level loader.</p> <p><c>erl_prim_loader</c> knows about the environment and how to - fetch modules. The loader could, for example, fetch files using - the file system (with absolute file names as input), or a - database (where the binary format of a module is stored).</p> + fetch modules.</p> <p>The <c>-loader Loader</c> command line flag can be used to choose the method used by the <c>erl_prim_loader</c>. Two <c>Loader</c> methods are supported by the Erlang runtime system: - <c>efile</c> and <c>inet</c>. If another loader is required, then - it has to be implemented by the user. The <c>Loader</c> provided - by the user must fulfill the protocol defined below, and it is - started with the <c>erl_prim_loader</c> by evaluating - <c>open_port({spawn,Loader},[binary])</c>.</p> + <c>efile</c> and <c>inet</c>.</p> <warning><p>The support for loading of code from archive files is experimental. The sole purpose of releasing it before it is ready @@ -83,9 +77,6 @@ started on each of hosts given in <c><anno>Hosts</anno></c> in order to answer the requests. See <seealso marker="kernel:erl_boot_server">erl_boot_server(3)</seealso>.</p> - <p>If <c>-loader</c> is something else, the given port program - is started. The port program is supposed to follow - the protocol specified below.</p> </desc> </func> <func> @@ -175,22 +166,6 @@ </funcs> <section> - <title>Protocol</title> - <p>The following protocol must be followed if a user provided - loader port program is used. The <c>Loader</c> port program is - started with the command - <c>open_port({spawn,Loader},[binary])</c>. The protocol is as - follows:</p> - <pre> -Function Send Receive -------------------------------------------------------------- -get_file [102 | FileName] [121 | BinaryFile] (on success) - [122] (failure) - -stop eof terminate</pre> - </section> - - <section> <title>Command Line Flags</title> <p>The <c>erl_prim_loader</c> module interprets the following command line flags:</p> @@ -199,10 +174,8 @@ stop eof terminate</pre> <item> <p>Specifies the name of the loader used by <c>erl_prim_loader</c>. <c>Loader</c> can be <c>efile</c> - (use the local file system), or <c>inet</c> (load using - the <c>boot_server</c> on another Erlang node). If - <c>Loader</c> is user defined, the defined <c>Loader</c> port - program is started.</p> + (use the local file system) or <c>inet</c> (load using + the <c>boot_server</c> on another Erlang node).</p> <p>If the <c>-loader</c> flag is omitted, it defaults to <c>efile</c>.</p> </item> diff --git a/erts/doc/src/notes.xml b/erts/doc/src/notes.xml index f27e73b9d3..5a65115cb2 100644 --- a/erts/doc/src/notes.xml +++ b/erts/doc/src/notes.xml @@ -31,8 +31,8 @@ </header> <p>This document describes the changes made to the ERTS application.</p> -<section><title>Erts 7.1</title> +<section><title>Erts 7.1</title> <section><title>Fixed Bugs and Malfunctions</title> <list> <item> @@ -981,6 +981,42 @@ </section> +<section><title>Erts 6.4.1.5</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixed a bug that could cause a crash dump to become + almost empty.</p> + <p> + Own Id: OTP-13150</p> + </item> + </list> + </section> + +</section> + +<section><title>Erts 6.4.1.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The 'raw' socket option could not be used multiple times + in one call to any e.g gen_tcp function because only one + of the occurrences were used. This bug has been fixed, + and also a small bug concerning propagating error codes + from within inet:setopts/2.</p> + <p> + Own Id: OTP-11482 Aux Id: seq12872 </p> + </item> + </list> + </section> + +</section> + + <section><title>Erts 6.4.1</title> <section><title>Fixed Bugs and Malfunctions</title> diff --git a/erts/emulator/beam/bif.c b/erts/emulator/beam/bif.c index 0bd46a2dae..a8cc19ee1f 100644 --- a/erts/emulator/beam/bif.c +++ b/erts/emulator/beam/bif.c @@ -4231,6 +4231,7 @@ BIF_RETTYPE list_to_pid_1(BIF_ALIST_1) goto bad; enp = erts_find_or_insert_node(dep->sysname, dep->creation); + ASSERT(enp != erts_this_node); etp = (ExternalThing *) HAlloc(BIF_P, EXTERNAL_THING_HEAD_SIZE + 1); etp->header = make_external_pid_header(1); diff --git a/erts/emulator/beam/dist.c b/erts/emulator/beam/dist.c index 0bbcc5f966..4846133aa6 100644 --- a/erts/emulator/beam/dist.c +++ b/erts/emulator/beam/dist.c @@ -2576,7 +2576,9 @@ int distribution_info(int to, void *arg) /* Called by break handler */ } for (dep = erts_not_connected_dist_entries; dep; dep = dep->next) { - info_dist_entry(to, arg, dep, 0, 0); + if (dep != erts_this_dist_entry) { + info_dist_entry(to, arg, dep, 0, 0); + } } return(0); @@ -2654,13 +2656,8 @@ BIF_RETTYPE setnode_2(BIF_ALIST_2) if (!net_kernel) goto error; - /* By setting dist_entry==erts_this_dist_entry and DISTRIBUTION on - net_kernel do_net_exist will be called when net_kernel - is terminated !! */ - (void) ERTS_PROC_SET_DIST_ENTRY(net_kernel, - ERTS_PROC_LOCK_MAIN, - erts_this_dist_entry); - erts_refc_inc(&erts_this_dist_entry->refc, 2); + /* By setting F_DISTRIBUTION on net_kernel, + * do_net_exist will be called when net_kernel is terminated !! */ net_kernel->flags |= F_DISTRIBUTION; if (net_kernel != BIF_P) @@ -3021,11 +3018,11 @@ BIF_RETTYPE nodes_1(BIF_ALIST_1) erts_smp_rwmtx_rlock(&erts_dist_table_rwmtx); - ASSERT(erts_no_of_not_connected_dist_entries >= 0); + ASSERT(erts_no_of_not_connected_dist_entries > 0); ASSERT(erts_no_of_hidden_dist_entries >= 0); ASSERT(erts_no_of_visible_dist_entries >= 0); if(not_connected) - length += erts_no_of_not_connected_dist_entries; + length += (erts_no_of_not_connected_dist_entries - 1); if(hidden) length += erts_no_of_hidden_dist_entries; if(visible) @@ -3047,8 +3044,10 @@ BIF_RETTYPE nodes_1(BIF_ALIST_1) #endif if(not_connected) for(dep = erts_not_connected_dist_entries; dep; dep = dep->next) { - result = CONS(hp, dep->sysname, result); - hp += 2; + if (dep != erts_this_dist_entry) { + result = CONS(hp, dep->sysname, result); + hp += 2; + } } if(hidden) for(dep = erts_hidden_dist_entries; dep; dep = dep->next) { diff --git a/erts/emulator/beam/erl_alloc.c b/erts/emulator/beam/erl_alloc.c index 55c164bf11..c3f4fe5a63 100644 --- a/erts/emulator/beam/erl_alloc.c +++ b/erts/emulator/beam/erl_alloc.c @@ -134,6 +134,7 @@ static ErtsAllocatorState_t binary_alloc_state; static ErtsAllocatorState_t ets_alloc_state; static ErtsAllocatorState_t driver_alloc_state; static ErtsAllocatorState_t fix_alloc_state; +static ErtsAllocatorState_t test_alloc_state; typedef struct { erts_smp_atomic32_t refc; @@ -233,6 +234,7 @@ typedef struct { struct au_init std_low_alloc; struct au_init ll_low_alloc; #endif + struct au_init test_alloc; } erts_alc_hndl_args_init_t; #define ERTS_AU_INIT__ {0, 0, 1, GOODFIT, DEFAULT_ALLCTR_INIT, {1,1,1,1}} @@ -432,6 +434,33 @@ set_default_fix_alloc_opts(struct au_init *ip, ip->init.util.acul = ERTS_ALC_DEFAULT_ACUL; } +static void +set_default_test_alloc_opts(struct au_init *ip) +{ + SET_DEFAULT_ALLOC_OPTS(ip); + ip->enable = 0; /* Disabled by default */ + ip->thr_spec = -1 * erts_no_schedulers; + ip->atype = AOFIRSTFIT; + ip->init.aoff.flavor = AOFF_BF; + ip->init.util.name_prefix = "test_"; + ip->init.util.alloc_no = ERTS_ALC_A_TEST; + ip->init.util.mmbcs = 0; /* Main carrier size */ + ip->init.util.ts = ERTS_ALC_MTA_TEST; + ip->init.util.acul = ERTS_ALC_DEFAULT_ACUL; + + /* Use a constant minimal MBC size */ +#if ERTS_SA_MB_CARRIERS + ip->init.util.smbcs = ERTS_SACRR_UNIT_SZ; + ip->init.util.lmbcs = ERTS_SACRR_UNIT_SZ; + ip->init.util.sbct = ERTS_SACRR_UNIT_SZ; +#else + ip->init.util.smbcs = 1 << 12; + ip->init.util.lmbcs = 1 << 12; + ip->init.util.sbct = 1 << 12; +#endif +} + + #ifdef ERTS_SMP static void @@ -613,6 +642,7 @@ erts_alloc_init(int *argc, char **argv, ErtsAllocInitOpts *eaiop) set_default_driver_alloc_opts(&init.driver_alloc); set_default_fix_alloc_opts(&init.fix_alloc, fix_type_sizes); + set_default_test_alloc_opts(&init.test_alloc); if (argc && argv) handle_args(argc, argv, &init); @@ -772,6 +802,7 @@ erts_alloc_init(int *argc, char **argv, ErtsAllocInitOpts *eaiop) set_au_allocator(ERTS_ALC_A_ETS, &init.ets_alloc, ncpu); set_au_allocator(ERTS_ALC_A_DRIVER, &init.driver_alloc, ncpu); set_au_allocator(ERTS_ALC_A_FIXED_SIZE, &init.fix_alloc, ncpu); + set_au_allocator(ERTS_ALC_A_TEST, &init.test_alloc, ncpu); for (i = ERTS_ALC_A_MIN; i <= ERTS_ALC_A_MAX; i++) { if (!erts_allctrs[i].alloc) @@ -833,6 +864,10 @@ erts_alloc_init(int *argc, char **argv, ErtsAllocInitOpts *eaiop) &init.fix_alloc, &fix_alloc_state); + start_au_allocator(ERTS_ALC_A_TEST, + &init.test_alloc, + &test_alloc_state); + erts_mtrace_install_wrapper_functions(); extra_block_size += erts_instr_init(init.instr.stat, init.instr.map); @@ -1418,6 +1453,7 @@ handle_args(int *argc, char **argv, erts_alc_hndl_args_init_t *init) &init->fix_alloc, &init->sl_alloc, &init->temp_alloc + /* test_alloc not affected by +Mea??? or +Mu??? */ }; int aui_sz = (int) sizeof(aui)/sizeof(aui[0]); char *arg; @@ -1508,6 +1544,9 @@ handle_args(int *argc, char **argv, erts_alc_hndl_args_init_t *init) case 'T': handle_au_arg(&init->temp_alloc, &argv[i][3], argv, &i, 0); break; + case 'Z': + handle_au_arg(&init->test_alloc, &argv[i][3], argv, &i, 0); + break; case 'Y': { /* sys_alloc */ if (has_prefix("tt", param+2)) { /* set trim threshold */ @@ -2222,11 +2261,12 @@ erts_memory(int *print_to_p, void *print_to_arg, void *proc, Eterm earg) return am_badarg; } - /* All alloc_util allocators *have* to be enabled */ + /* All alloc_util allocators *have* to be enabled, except test_alloc */ for (ai = ERTS_ALC_A_MIN; ai <= ERTS_ALC_A_MAX; ai++) { switch (ai) { case ERTS_ALC_A_SYSTEM: + case ERTS_ALC_A_TEST: break; default: if (!erts_allctrs_info[ai].enabled @@ -2267,6 +2307,8 @@ erts_memory(int *print_to_p, void *print_to_arg, void *proc, Eterm earg) * contain any allocated memory. */ continue; + case ERTS_ALC_A_TEST: + continue; case ERTS_ALC_A_EHEAP: save = &size.processes; break; @@ -2675,14 +2717,17 @@ erts_alloc_util_allocators(void *proc) /* * Currently all allocators except sys_alloc are * alloc_util allocators. + * Also hide test_alloc which is disabled by default + * and only intended for our own testing. */ - sz = ((ERTS_ALC_A_MAX + 1 - ERTS_ALC_A_MIN) - 1)*2; + sz = ((ERTS_ALC_A_MAX + 1 - ERTS_ALC_A_MIN) - 2)*2; ASSERT(sz > 0); hp = HAlloc((Process *) proc, sz); res = NIL; for (i = ERTS_ALC_A_MAX; i >= ERTS_ALC_A_MIN; i--) { switch (i) { case ERTS_ALC_A_SYSTEM: + case ERTS_ALC_A_TEST: break; default: { char *alc_str = (char *) ERTS_ALC_A2AD(i); @@ -3566,6 +3611,41 @@ UWord erts_alc_test(UWord op, UWord a1, UWord a2, UWord a3) #else case 0xf13: return (UWord) 0; #endif + case 0xf14: return (UWord) erts_alloc(ERTS_ALC_T_TEST, (Uint)a1); + + case 0xf15: erts_free(ERTS_ALC_T_TEST, (void*)a1); return 0; + + case 0xf16: { + Uint extra_hdr_sz = UNIT_CEILING((Uint)a1); + ErtsAllocatorThrSpec_t* ts = &erts_allctr_thr_spec[ERTS_ALC_A_TEST]; + Uint offset = ts->allctr[0]->mbc_header_size; + void* orig_creating_mbc = ts->allctr[0]->creating_mbc; + void* orig_destroying_mbc = ts->allctr[0]->destroying_mbc; + void* new_creating_mbc = *(void**)a2; /* inout arg */ + void* new_destroying_mbc = *(void**)a3; /* inout arg */ + int i; + + for (i=0; i < ts->size; i++) { + Allctr_t* ap = ts->allctr[i]; + if (ap->mbc_header_size != offset + || ap->creating_mbc != orig_creating_mbc + || ap->destroying_mbc != orig_destroying_mbc + || ap->mbc_list.first != NULL) + return -1; + } + for (i=0; i < ts->size; i++) { + ts->allctr[i]->mbc_header_size += extra_hdr_sz; + ts->allctr[i]->creating_mbc = new_creating_mbc; + ts->allctr[i]->destroying_mbc = new_destroying_mbc; + } + *(void**)a2 = orig_creating_mbc; + *(void**)a3 = orig_destroying_mbc; + return offset; + } + case 0xf17: { + ErtsAllocatorThrSpec_t* ts = &erts_allctr_thr_spec[ERTS_ALC_A_TEST]; + return ts->allctr[0]->largest_mbc_size; + } default: break; } diff --git a/erts/emulator/beam/erl_alloc.types b/erts/emulator/beam/erl_alloc.types index b1d511ab78..1ecebdeb07 100644 --- a/erts/emulator/beam/erl_alloc.types +++ b/erts/emulator/beam/erl_alloc.types @@ -112,7 +112,7 @@ allocator STANDARD_LOW false std_low_alloc allocator BINARY true binary_alloc allocator DRIVER true driver_alloc - +allocator TEST true test_alloc # --- Class declarations ----------------------------------------------------- # @@ -456,4 +456,7 @@ type CON_VPRINTF_BUF TEMPORARY SYSTEM con_vprintf_buf +endif +# This type should only be used for test +type TEST TEST SYSTEM testing + # ---------------------------------------------------------------------------- diff --git a/erts/emulator/beam/erl_alloc_util.c b/erts/emulator/beam/erl_alloc_util.c index 236ee35d18..8229a15824 100644 --- a/erts/emulator/beam/erl_alloc_util.c +++ b/erts/emulator/beam/erl_alloc_util.c @@ -1437,6 +1437,16 @@ erts_alcu_fix_alloc_shrink(Allctr_t *allctr, erts_aint32_t flgs) static void dealloc_carrier(Allctr_t *allctr, Carrier_t *crr, int superaligned); +static ERTS_INLINE void +dealloc_mbc(Allctr_t *allctr, Carrier_t *crr) +{ + ASSERT(IS_MB_CARRIER(crr)); + if (allctr->destroying_mbc) + allctr->destroying_mbc(allctr, crr); + + dealloc_carrier(allctr, crr, 1); +} + #ifdef ERTS_SMP static ERTS_INLINE Allctr_t* @@ -3149,7 +3159,7 @@ cpool_fetch(Allctr_t *allctr, UWord size) cpool_entrance = sentinel; cpdp = cpool_aint2cpd(cpool_read(&cpool_entrance->prev)); if (cpdp == sentinel) - return NULL; + goto check_dc_list; } has_passed_sentinel = 0; @@ -3160,18 +3170,18 @@ cpool_fetch(Allctr_t *allctr, UWord size) if (cpool_entrance == sentinel) { cpdp = cpool_aint2cpd(cpool_read(&cpdp->prev)); if (cpdp == sentinel) - return NULL; + break; } i = 0; /* Last one to inspect */ } else if (cpdp == sentinel) { if (has_passed_sentinel) { /* We been here before. cpool_entrance must have been removed */ - return NULL; + break; } cpdp = cpool_aint2cpd(cpool_read(&cpdp->prev)); if (cpdp == sentinel) - return NULL; + break; has_passed_sentinel = 1; } crr = (Carrier_t *)(((char *)cpdp) - offsetof(Carrier_t, cpool)); @@ -3195,10 +3205,12 @@ cpool_fetch(Allctr_t *allctr, UWord size) return NULL; } +check_dc_list: /* Last; check our own pending dealloc carrier list... */ crr = allctr->cpool.dc_list.last; while (crr) { if (erts_atomic_read_nob(&crr->cpool.max_size) >= size) { + Block_t* blk; unlink_carrier(&allctr->cpool.dc_list, crr); #ifdef ERTS_ALC_CPOOL_DEBUG ERTS_ALC_CPOOL_ASSERT(erts_smp_atomic_xchg_nob(&crr->allctr, @@ -3207,6 +3219,9 @@ cpool_fetch(Allctr_t *allctr, UWord size) #else erts_smp_atomic_set_nob(&crr->allctr, ((erts_aint_t) allctr)); #endif + blk = MBC_TO_FIRST_BLK(allctr, crr); + ASSERT(FBLK_TO_MBC(blk) == crr); + allctr->link_free_block(allctr, blk); return crr; } crr = crr->prev; @@ -3237,7 +3252,7 @@ check_pending_dealloc_carrier(Allctr_t *allctr, dcrr = crr; crr = crr->next; - dealloc_carrier(allctr, dcrr, 1); + dealloc_mbc(allctr, dcrr); i++; } while (crr && i < ERTS_ALC_MAX_DEALLOC_CARRIER); @@ -3268,18 +3283,20 @@ static void schedule_dealloc_carrier(Allctr_t *allctr, Carrier_t *crr) { Allctr_t *orig_allctr; + Block_t *blk; int check_pending_dealloc; erts_aint_t max_size; + ASSERT(IS_MB_CARRIER(crr)); + if (!ERTS_ALC_IS_CPOOL_ENABLED(allctr)) { - dealloc_carrier(allctr, crr, 1); + dealloc_mbc(allctr, crr); return; } orig_allctr = crr->cpool.orig_allctr; if (allctr != orig_allctr) { - Block_t *blk = MBC_TO_FIRST_BLK(allctr, crr); int cinit = orig_allctr->dd.ix - allctr->dd.ix; /* @@ -3296,6 +3313,7 @@ schedule_dealloc_carrier(Allctr_t *allctr, Carrier_t *crr) * since the block is an mbc block that is free and last * in the carrier. */ + blk = MBC_TO_FIRST_BLK(allctr, crr); ERTS_ALC_CPOOL_ASSERT(IS_FREE_LAST_MBC_BLK(blk)); ERTS_ALC_CPOOL_ASSERT(IS_MBC_FIRST_ABLK(allctr, blk)); @@ -3315,11 +3333,13 @@ schedule_dealloc_carrier(Allctr_t *allctr, Carrier_t *crr) if (crr->cpool.thr_prgr == ERTS_THR_PRGR_INVALID || erts_thr_progress_has_reached(crr->cpool.thr_prgr)) { - dealloc_carrier(allctr, crr, 1); + dealloc_mbc(allctr, crr); return; } - max_size = (erts_aint_t) allctr->largest_fblk_in_mbc(allctr, crr); + blk = MBC_TO_FIRST_BLK(allctr, crr); + ASSERT(IS_FREE_LAST_MBC_BLK(blk)); + max_size = (erts_aint_t) MBC_FBLK_SZ(blk); erts_atomic_set_nob(&crr->cpool.max_size, max_size); crr->next = NULL; @@ -3894,9 +3914,6 @@ destroy_carrier(Allctr_t *allctr, Block_t *blk, Carrier_t **busy_pcrr_pp) } #endif - if (allctr->destroying_mbc) - (*allctr->destroying_mbc)(allctr, crr); - #ifdef ERTS_SMP if (busy_pcrr_pp && *busy_pcrr_pp) { ERTS_ALC_CPOOL_ASSERT(*busy_pcrr_pp == crr); @@ -3920,12 +3937,15 @@ destroy_carrier(Allctr_t *allctr, Block_t *blk, Carrier_t **busy_pcrr_pp) else #endif STAT_SYS_ALLOC_MBC_FREE(allctr, crr_sz); + + if (allctr->remove_mbc) + allctr->remove_mbc(allctr, crr); } #ifdef ERTS_SMP schedule_dealloc_carrier(allctr, crr); #else - dealloc_carrier(allctr, crr, 1); + dealloc_mbc(allctr, crr); #endif } } @@ -6054,6 +6074,16 @@ erts_alcu_test(UWord op, UWord a1, UWord a2) case 0x023: return (UWord) 0; case 0x024: return (UWord) 0; #endif + case 0x025: /* UMEM2BLK_TEST*/ +#ifdef DEBUG +# ifdef HARD_DEBUG + return (UWord)UMEM2BLK(a1-3*sizeof(UWord)); +# else + return (UWord)UMEM2BLK(a1-2*sizeof(UWord)); +# endif +#else + return (UWord)UMEM2BLK(a1); +#endif default: ASSERT(0); return ~((UWord) 0); } diff --git a/erts/emulator/beam/erl_alloc_util.h b/erts/emulator/beam/erl_alloc_util.h index df1f0aa65a..f4a2ae7ff3 100644 --- a/erts/emulator/beam/erl_alloc_util.h +++ b/erts/emulator/beam/erl_alloc_util.h @@ -277,7 +277,7 @@ typedef struct ErtsDoubleLink_t_ { typedef struct { erts_atomic_t next; erts_atomic_t prev; - Allctr_t *orig_allctr; + Allctr_t *orig_allctr; /* read-only while carrier is alive */ ErtsThrPrgrVal thr_prgr; erts_atomic_t max_size; UWord abandon_limit; diff --git a/erts/emulator/beam/erl_ao_firstfit_alloc.c b/erts/emulator/beam/erl_ao_firstfit_alloc.c index 7c2a5c3323..19420af8ab 100644 --- a/erts/emulator/beam/erl_ao_firstfit_alloc.c +++ b/erts/emulator/beam/erl_ao_firstfit_alloc.c @@ -209,7 +209,9 @@ static Block_t* aoff_get_free_block(Allctr_t *, Uint, Block_t *, Uint); static void aoff_link_free_block(Allctr_t *, Block_t*); static void aoff_unlink_free_block(Allctr_t *allctr, Block_t *del); static void aoff_creating_mbc(Allctr_t*, Carrier_t*); +#ifdef DEBUG static void aoff_destroying_mbc(Allctr_t*, Carrier_t*); +#endif static void aoff_add_mbc(Allctr_t*, Carrier_t*); static void aoff_remove_mbc(Allctr_t*, Carrier_t*); static UWord aoff_largest_fblk_in_mbc(Allctr_t*, Carrier_t*); @@ -271,7 +273,11 @@ erts_aoffalc_start(AOFFAllctr_t *alc, allctr->get_next_mbc_size = NULL; allctr->creating_mbc = aoff_creating_mbc; +#ifdef DEBUG allctr->destroying_mbc = aoff_destroying_mbc; +#else + allctr->destroying_mbc = NULL; +#endif allctr->add_mbc = aoff_add_mbc; allctr->remove_mbc = aoff_remove_mbc; allctr->largest_fblk_in_mbc = aoff_largest_fblk_in_mbc; @@ -885,17 +891,18 @@ static void aoff_creating_mbc(Allctr_t *allctr, Carrier_t *carrier) HARD_CHECK_TREE(NULL, 0, *root, 0); } +#define IS_CRR_IN_TREE(CRR,ROOT) \ + ((CRR)->rbt_node.parent || (ROOT) == &(CRR)->rbt_node) + +#ifdef DEBUG static void aoff_destroying_mbc(Allctr_t *allctr, Carrier_t *carrier) { AOFFAllctr_t *alc = (AOFFAllctr_t *) allctr; AOFF_Carrier_t *crr = (AOFF_Carrier_t*) carrier; - AOFF_RBTree_t *root = alc->mbc_root; - if (crr->rbt_node.parent || &crr->rbt_node == root) { - aoff_remove_mbc(allctr, carrier); - } - /*else already removed */ + ASSERT(!IS_CRR_IN_TREE(crr, alc->mbc_root)); } +#endif static void aoff_add_mbc(Allctr_t *allctr, Carrier_t *carrier) { @@ -903,6 +910,7 @@ static void aoff_add_mbc(Allctr_t *allctr, Carrier_t *carrier) AOFF_Carrier_t *crr = (AOFF_Carrier_t*) carrier; AOFF_RBTree_t **root = &alc->mbc_root; + ASSERT(!IS_CRR_IN_TREE(crr, *root)); HARD_CHECK_TREE(NULL, 0, *root, 0); /* Link carrier in address order tree @@ -919,6 +927,10 @@ static void aoff_remove_mbc(Allctr_t *allctr, Carrier_t *carrier) AOFF_RBTree_t **root = &alc->mbc_root; ASSERT(allctr == ERTS_ALC_CARRIER_TO_ALLCTR(carrier)); + + if (!IS_CRR_IN_TREE(crr,*root)) + return; + HARD_CHECK_TREE(NULL, 0, *root, 0); rbt_delete(root, &crr->rbt_node); diff --git a/erts/emulator/beam/erl_driver.h b/erts/emulator/beam/erl_driver.h index 6b406d069c..dbb4d719c1 100644 --- a/erts/emulator/beam/erl_driver.h +++ b/erts/emulator/beam/erl_driver.h @@ -696,8 +696,8 @@ EXTERN int driver_dl_close(void *); EXTERN char *driver_dl_error(void); /* environment */ -EXTERN int erl_drv_putenv(char *key, char *value); -EXTERN int erl_drv_getenv(char *key, char *value, size_t *value_size); +EXTERN int erl_drv_putenv(const char *key, char *value); +EXTERN int erl_drv_getenv(const char *key, char *value, size_t *value_size); #ifdef __OSE__ typedef ErlDrvUInt ErlDrvOseEventId; diff --git a/erts/emulator/beam/erl_gc.c b/erts/emulator/beam/erl_gc.c index d2604f1595..2f21111a2e 100644 --- a/erts/emulator/beam/erl_gc.c +++ b/erts/emulator/beam/erl_gc.c @@ -1237,6 +1237,7 @@ major_collection(Process* p, int need, Eterm* objv, int nobj, Uint *recl) Uint oh_size = (char *) OLD_HTOP(p) - oh; Uint n; Uint new_sz; + int done; /* * Do a fullsweep GC. First figure out the size of the heap @@ -1440,6 +1441,8 @@ major_collection(Process* p, int need, Eterm* objv, int nobj, Uint *recl) *recl += size_before - (HEAP_TOP(p) - HEAP_START(p)); + remove_message_buffers(p); + { ErlMessage *msgp; @@ -1458,15 +1461,21 @@ major_collection(Process* p, int need, Eterm* objv, int nobj, Uint *recl) } } - adjust_after_fullsweep(p, need, objv, nobj); - -#ifdef HARDDEBUG - disallow_heap_frag_ref_in_heap(p); -#endif - remove_message_buffers(p); + if (MBUF(p)) { + /* This is a very rare case when distributed messages copied above + * contained maps so big they did not fit on the heap causing the + * factory to create heap frags. + * Solution: Trigger a minor gc (without tenuring) + */ + HIGH_WATER(p) = HEAP_START(p); + done = 0; + } else { + adjust_after_fullsweep(p, need, objv, nobj); + done = 1; + } ErtsGcQuickSanityCheck(p); - return 1; /* We are done. */ + return done; } static void @@ -1955,7 +1964,18 @@ collect_heap_frags(Process* p, Eterm* n_hstart, Eterm* n_htop, if (p->dictionary != NULL) { disallow_heap_frag_ref(p, n_htop, p->dictionary->data, p->dictionary->used); } - disallow_heap_frag_ref_in_heap(p); + /* OTP-18: Actually we do allow references from heap to heap fragments now. + This can happen when doing "binary_to_term" with a "fat" map contained + in another term. A "fat" map is a hashmap with higher heap demand than + first estimated by "binary_to_term" causing the factory to allocate + additional heap (fragments) for the hashmap tree nodes. + Run map_SUITE:t_gc_rare_map_overflow to provoke this. + + Inverted references like this does not matter however. The copy done + below by move_one_area() with move markers in the fragments and the + sweeping done later by the GC should make everything ok in the end. + */ + /***disallow_heap_frag_ref_in_heap(p);***/ #endif /* diff --git a/erts/emulator/beam/erl_nif.c b/erts/emulator/beam/erl_nif.c index add4a66f90..d7a2076d85 100644 --- a/erts/emulator/beam/erl_nif.c +++ b/erts/emulator/beam/erl_nif.c @@ -1173,6 +1173,7 @@ ErlNifTid enif_thread_self(void) { return erl_drv_thread_self(); } int enif_equal_tids(ErlNifTid tid1, ErlNifTid tid2) { return erl_drv_equal_tids(tid1,tid2); } void enif_thread_exit(void *resp) { erl_drv_thread_exit(resp); } int enif_thread_join(ErlNifTid tid, void **respp) { return erl_drv_thread_join(tid,respp); } +int enif_getenv(const char *key, char *value, size_t *value_size) { return erl_drv_getenv(key, value, value_size); } int enif_fprintf(void* filep, const char* format, ...) { diff --git a/erts/emulator/beam/erl_nif.h b/erts/emulator/beam/erl_nif.h index 7d880126f8..5e39343e9b 100644 --- a/erts/emulator/beam/erl_nif.h +++ b/erts/emulator/beam/erl_nif.h @@ -48,9 +48,10 @@ ** add ErlNifEntry options ** add ErlNifFunc flags ** 2.8: 18.0 add enif_has_pending_exception +** 2.9: 18.2 enif_getenv */ #define ERL_NIF_MAJOR_VERSION 2 -#define ERL_NIF_MINOR_VERSION 8 +#define ERL_NIF_MINOR_VERSION 9 /* * The emulator will refuse to load a nif-lib with a major version @@ -231,6 +232,7 @@ typedef enum { # define ERL_NIF_API_FUNC_DECL(RET_TYPE, NAME, ARGS) RET_TYPE (*NAME) ARGS typedef struct { # include "erl_nif_api_funcs.h" + void* erts_alc_test; } TWinDynNifCallbacks; extern TWinDynNifCallbacks WinDynNifCallbacks; # undef ERL_NIF_API_FUNC_DECL diff --git a/erts/emulator/beam/erl_nif_api_funcs.h b/erts/emulator/beam/erl_nif_api_funcs.h index 2f2180e1aa..08b9afc6af 100644 --- a/erts/emulator/beam/erl_nif_api_funcs.h +++ b/erts/emulator/beam/erl_nif_api_funcs.h @@ -159,6 +159,7 @@ ERL_NIF_API_FUNC_DECL(int, enif_map_iterator_get_pair, (ErlNifEnv *env, ErlNifMa ERL_NIF_API_FUNC_DECL(ERL_NIF_TERM,enif_schedule_nif,(ErlNifEnv*,const char*,int,ERL_NIF_TERM (*)(ErlNifEnv*,int,const ERL_NIF_TERM[]),int,const ERL_NIF_TERM[])); ERL_NIF_API_FUNC_DECL(int, enif_has_pending_exception, (ErlNifEnv *env, ERL_NIF_TERM* reason)); ERL_NIF_API_FUNC_DECL(ERL_NIF_TERM, enif_raise_exception, (ErlNifEnv *env, ERL_NIF_TERM reason)); +ERL_NIF_API_FUNC_DECL(int,enif_getenv,(const char* key, char* value, size_t* value_size)); /* ** ADD NEW ENTRIES HERE (before this comment) !!! @@ -310,6 +311,7 @@ ERL_NIF_API_FUNC_DECL(int,enif_is_on_dirty_scheduler,(ErlNifEnv*)); # define enif_schedule_nif ERL_NIF_API_FUNC_MACRO(enif_schedule_nif) # define enif_has_pending_exception ERL_NIF_API_FUNC_MACRO(enif_has_pending_exception) # define enif_raise_exception ERL_NIF_API_FUNC_MACRO(enif_raise_exception) +# define enif_getenv ERL_NIF_API_FUNC_MACRO(enif_getenv) /* ** ADD NEW ENTRIES HERE (before this comment) diff --git a/erts/emulator/beam/erl_node_tables.c b/erts/emulator/beam/erl_node_tables.c index 2fb790b953..a7d0511bf9 100644 --- a/erts/emulator/beam/erl_node_tables.c +++ b/erts/emulator/beam/erl_node_tables.c @@ -37,18 +37,18 @@ erts_smp_rwmtx_t erts_node_table_rwmtx; DistEntry *erts_hidden_dist_entries; DistEntry *erts_visible_dist_entries; -DistEntry *erts_not_connected_dist_entries; +DistEntry *erts_not_connected_dist_entries; /* including erts_this_dist_entry */ Sint erts_no_of_hidden_dist_entries; Sint erts_no_of_visible_dist_entries; -Sint erts_no_of_not_connected_dist_entries; +Sint erts_no_of_not_connected_dist_entries; /* including erts_this_dist_entry */ DistEntry *erts_this_dist_entry; ErlNode *erts_this_node; char erts_this_node_sysname_BUFFER[256], *erts_this_node_sysname = "uninitialized yet"; -static Uint node_entries; -static Uint dist_entries; +static Uint node_entries = 0; +static Uint dist_entries = 0; static int references_atoms_need_init = 1; @@ -91,9 +91,6 @@ dist_table_alloc(void *dep_tmpl) erts_smp_rwmtx_opt_t rwmtx_opt = ERTS_SMP_RWMTX_OPT_DEFAULT_INITER; rwmtx_opt.type = ERTS_SMP_RWMTX_TYPE_FREQUENT_READ; - if(((DistEntry *) dep_tmpl) == erts_this_dist_entry) - return dep_tmpl; - sysname = ((DistEntry *) dep_tmpl)->sysname; chnl_nr = make_small((Uint) atom_val(sysname)); dep = (DistEntry *) erts_alloc(ERTS_ALC_T_DIST_ENTRY, sizeof(DistEntry)); @@ -132,7 +129,9 @@ dist_table_alloc(void *dep_tmpl) /* Link in */ - /* All new dist entries are "not connected" */ + /* All new dist entries are "not connected". + * erts_this_dist_entry is also always included among "not connected" + */ dep->next = erts_not_connected_dist_entries; if(erts_not_connected_dist_entries) { ASSERT(erts_not_connected_dist_entries->prev == NULL); @@ -149,9 +148,6 @@ dist_table_free(void *vdep) { DistEntry *dep = (DistEntry *) vdep; - if(dep == erts_this_dist_entry) - return; - ASSERT(is_nil(dep->cid)); ASSERT(dep->nlinks == NULL); ASSERT(dep->node_links == NULL); @@ -186,7 +182,7 @@ dist_table_free(void *vdep) #endif erts_free(ERTS_ALC_T_DIST_ENTRY, (void *) dep); - ASSERT(dist_entries > 1); + ASSERT(dist_entries > 0); dist_entries--; } @@ -306,7 +302,7 @@ static void try_delete_dist_entry(void *vdep) * thread incremented refc twice. Once for the new reference * and once for this thread. * - * If refc reach -1, noone has used the entry since we + * If refc reach -1, no one has used the entry since we * set up the timer. Delete the entry. * * If refc reach 0, the entry is currently not in use @@ -369,8 +365,7 @@ erts_dist_table_size(void) ASSERT(dist_entries == (erts_no_of_visible_dist_entries + erts_no_of_hidden_dist_entries - + erts_no_of_not_connected_dist_entries - + 1 /* erts_this_dist_entry */)); + + erts_no_of_not_connected_dist_entries)); #endif res = (hash_table_sz(&erts_dist_table) @@ -543,9 +538,6 @@ node_table_alloc(void *venp_tmpl) { ErlNode *enp; - if(((ErlNode *) venp_tmpl) == erts_this_node) - return venp_tmpl; - enp = (ErlNode *) erts_alloc(ERTS_ALC_T_NODE_ENTRY, sizeof(ErlNode)); node_entries++; @@ -563,8 +555,7 @@ node_table_free(void *venp) { ErlNode *enp = (ErlNode *) venp; - if(enp == erts_this_node) - return; + ERTS_SMP_LC_ASSERT(enp != erts_this_node || erts_thr_progress_is_blocking()); erts_deref_dist_entry(enp->dist_entry); #ifdef DEBUG @@ -572,7 +563,7 @@ node_table_free(void *venp) #endif erts_free(ERTS_ALC_T_NODE_ENTRY, venp); - ASSERT(node_entries > 1); + ASSERT(node_entries > 0); node_entries--; } @@ -650,7 +641,7 @@ static void try_delete_node(void *venp) * thread incremented refc twice. Once for the new reference * and once for this thread. * - * If refc reach -1, noone has used the entry since we + * If refc reach -1, no one has used the entry since we * set up the timer. Delete the entry. * * If refc reach 0, the entry is currently not in use @@ -747,25 +738,20 @@ void erts_print_node_info(int to, void erts_set_this_node(Eterm sysname, Uint creation) { - erts_smp_rwmtx_rwlock(&erts_node_table_rwmtx); - erts_smp_rwmtx_rwlock(&erts_dist_table_rwmtx); + ERTS_SMP_LC_ASSERT(erts_thr_progress_is_blocking()); + ASSERT(erts_refc_read(&erts_this_dist_entry->refc, 2)); - (void) hash_erase(&erts_dist_table, (void *) erts_this_dist_entry); - erts_this_dist_entry->sysname = sysname; - erts_this_dist_entry->creation = creation; - (void) hash_put(&erts_dist_table, (void *) erts_this_dist_entry); + if (erts_refc_dectest(&erts_this_node->refc, 0) == 0) + try_delete_node(erts_this_node); - (void) hash_erase(&erts_node_table, (void *) erts_this_node); - erts_this_node->sysname = sysname; - erts_this_node->creation = creation; - erts_this_node_sysname = erts_this_node_sysname_BUFFER; - erts_snprintf(erts_this_node_sysname, sizeof(erts_this_node_sysname_BUFFER), - "%T", sysname); - (void) hash_put(&erts_node_table, (void *) erts_this_node); + if (erts_refc_dectest(&erts_this_dist_entry->refc, 0) == 0) + try_delete_dist_entry(erts_this_dist_entry); - erts_smp_rwmtx_rwunlock(&erts_dist_table_rwmtx); - erts_smp_rwmtx_rwunlock(&erts_node_table_rwmtx); + erts_this_node = NULL; /* to make sure refc is bumped for this node */ + erts_this_node = erts_find_or_insert_node(sysname, creation); + erts_this_dist_entry = erts_this_node->dist_entry; + erts_refc_inc(&erts_this_dist_entry->refc, 2); } Uint @@ -782,6 +768,7 @@ void erts_init_node_tables(int dd_sec) { erts_smp_rwmtx_opt_t rwmtx_opt = ERTS_SMP_RWMTX_OPT_DEFAULT_INITER; HashFunctions f; + ErlNode node_tmpl; if (dd_sec == ERTS_NODE_TAB_DELAY_GC_INFINITY) node_tab_delete_delay = (ErtsMonotonicTime) -1; @@ -793,16 +780,21 @@ void erts_init_node_tables(int dd_sec) rwmtx_opt.type = ERTS_SMP_RWMTX_TYPE_FREQUENT_READ; rwmtx_opt.lived = ERTS_SMP_RWMTX_LONG_LIVED; + erts_smp_rwmtx_init_opt(&erts_node_table_rwmtx, &rwmtx_opt, "node_table"); + erts_smp_rwmtx_init_opt(&erts_dist_table_rwmtx, &rwmtx_opt, "dist_table"); + f.hash = (H_FUN) dist_table_hash; f.cmp = (HCMP_FUN) dist_table_cmp; f.alloc = (HALLOC_FUN) dist_table_alloc; f.free = (HFREE_FUN) dist_table_free; - - erts_this_dist_entry = erts_alloc(ERTS_ALC_T_DIST_ENTRY, sizeof(DistEntry)); - dist_entries = 1; - hash_init(ERTS_ALC_T_DIST_TABLE, &erts_dist_table, "dist_table", 11, f); + f.hash = (H_FUN) node_table_hash; + f.cmp = (HCMP_FUN) node_table_cmp; + f.alloc = (HALLOC_FUN) node_table_alloc; + f.free = (HFREE_FUN) node_table_free; + hash_init(ERTS_ALC_T_NODE_TABLE, &erts_node_table, "node_table", 11, f); + erts_hidden_dist_entries = NULL; erts_visible_dist_entries = NULL; erts_not_connected_dist_entries = NULL; @@ -810,69 +802,23 @@ void erts_init_node_tables(int dd_sec) erts_no_of_visible_dist_entries = 0; erts_no_of_not_connected_dist_entries = 0; - erts_this_dist_entry->next = NULL; - erts_this_dist_entry->prev = NULL; - erts_refc_init(&erts_this_dist_entry->refc, 1); /* erts_this_node */ - - erts_smp_rwmtx_init_opt_x(&erts_this_dist_entry->rwmtx, - &rwmtx_opt, - "dist_entry", - make_small(ERST_INTERNAL_CHANNEL_NO)); - erts_this_dist_entry->sysname = am_Noname; - erts_this_dist_entry->cid = NIL; - erts_this_dist_entry->connection_id = 0; - erts_this_dist_entry->status = 0; - erts_this_dist_entry->flags = 0; - erts_this_dist_entry->version = 0; - - erts_smp_mtx_init_x(&erts_this_dist_entry->lnk_mtx, - "dist_entry_links", - make_small(ERST_INTERNAL_CHANNEL_NO)); - erts_this_dist_entry->node_links = NULL; - erts_this_dist_entry->nlinks = NULL; - erts_this_dist_entry->monitors = NULL; - - erts_smp_mtx_init_x(&erts_this_dist_entry->qlock, - "dist_entry_out_queue", - make_small(ERST_INTERNAL_CHANNEL_NO)); - erts_this_dist_entry->qflgs = 0; - erts_this_dist_entry->qsize = 0; - erts_this_dist_entry->out_queue.first = NULL; - erts_this_dist_entry->out_queue.last = NULL; - erts_this_dist_entry->suspended = NULL; - - erts_this_dist_entry->finalized_out_queue.first = NULL; - erts_this_dist_entry->finalized_out_queue.last = NULL; - erts_smp_atomic_init_nob(&erts_this_dist_entry->dist_cmd_scheduled, 0); - erts_port_task_handle_init(&erts_this_dist_entry->dist_cmd); - erts_this_dist_entry->send = NULL; - erts_this_dist_entry->cache = NULL; - - (void) hash_put(&erts_dist_table, (void *) erts_this_dist_entry); - - f.hash = (H_FUN) node_table_hash; - f.cmp = (HCMP_FUN) node_table_cmp; - f.alloc = (HALLOC_FUN) node_table_alloc; - f.free = (HFREE_FUN) node_table_free; + node_tmpl.sysname = am_Noname; + node_tmpl.creation = 0; + erts_this_node = hash_put(&erts_node_table, &node_tmpl); + /* +1 for erts_this_node */ + erts_refc_init(&erts_this_node->refc, 1); - hash_init(ERTS_ALC_T_NODE_TABLE, &erts_node_table, "node_table", 11, f); + ASSERT(erts_this_node->dist_entry != NULL); + erts_this_dist_entry = erts_this_node->dist_entry; + /* +1 for erts_this_dist_entry */ + /* +1 for erts_this_node->dist_entry */ + erts_refc_init(&erts_this_dist_entry->refc, 2); - erts_this_node = erts_alloc(ERTS_ALC_T_NODE_ENTRY, sizeof(ErlNode)); - node_entries = 1; - erts_refc_init(&erts_this_node->refc, 1); /* The system itself */ - erts_this_node->sysname = am_Noname; - erts_this_node->creation = 0; - erts_this_node->dist_entry = erts_this_dist_entry; erts_this_node_sysname = erts_this_node_sysname_BUFFER; erts_snprintf(erts_this_node_sysname, sizeof(erts_this_node_sysname_BUFFER), "%T", erts_this_node->sysname); - (void) hash_put(&erts_node_table, (void *) erts_this_node); - - erts_smp_rwmtx_init_opt(&erts_node_table_rwmtx, &rwmtx_opt, "node_table"); - erts_smp_rwmtx_init_opt(&erts_dist_table_rwmtx, &rwmtx_opt, "dist_table"); - references_atoms_need_init = 1; } @@ -1410,6 +1356,10 @@ setup_reference_table(void) SYSTEM_REF, TUPLE2(&heap[0], AM_system, am_undefined)); + insert_dist_entry(erts_this_dist_entry, + SYSTEM_REF, + TUPLE2(&heap[0], AM_system, am_undefined), + erts_this_node->creation); UnUseTmpHeapNoproc(3); max = erts_ptab_max(&erts_proc); @@ -1472,12 +1422,6 @@ setup_reference_table(void) insert_links(ERTS_P_LINKS(proc), proc->common.id); if (ERTS_P_MONITORS(proc)) insert_monitors(ERTS_P_MONITORS(proc), proc->common.id); - /* Insert controller */ - { - DistEntry *dep = ERTS_PROC_GET_DIST_ENTRY(proc); - if (dep) - insert_dist_entry(dep, CTRL_REF, proc->common.id, 0); - } } } diff --git a/erts/emulator/beam/erl_process.c b/erts/emulator/beam/erl_process.c index 3b1b593d1c..d583118e7b 100644 --- a/erts/emulator/beam/erl_process.c +++ b/erts/emulator/beam/erl_process.c @@ -625,11 +625,6 @@ erts_pre_init_process(void) erts_psd_required_locks[ERTS_PSD_SCHED_ID].set_locks = ERTS_PSD_SCHED_ID_SET_LOCKS; - erts_psd_required_locks[ERTS_PSD_DIST_ENTRY].get_locks - = ERTS_PSD_DIST_ENTRY_GET_LOCKS; - erts_psd_required_locks[ERTS_PSD_DIST_ENTRY].set_locks - = ERTS_PSD_DIST_ENTRY_SET_LOCKS; - erts_psd_required_locks[ERTS_PSD_CALL_TIME_BP].get_locks = ERTS_PSD_CALL_TIME_BP_GET_LOCKS; erts_psd_required_locks[ERTS_PSD_CALL_TIME_BP].set_locks @@ -12373,9 +12368,7 @@ erts_continue_exit_process(Process *p) erts_proc_dec_refc(p); } - dep = ((p->flags & F_DISTRIBUTION) - ? ERTS_PROC_SET_DIST_ENTRY(p, ERTS_PROC_LOCKS_ALL, NULL) - : NULL); + dep = (p->flags & F_DISTRIBUTION) ? erts_this_dist_entry : NULL; scb = ERTS_PROC_SET_SAVED_CALLS_BUF(p, ERTS_PROC_LOCKS_ALL, NULL); pbt = ERTS_PROC_SET_CALL_TIME(p, ERTS_PROC_LOCKS_ALL, NULL); nif_export = ERTS_PROC_SET_NIF_TRAP_EXPORT(p, ERTS_PROC_LOCKS_ALL, NULL); @@ -12387,8 +12380,6 @@ erts_continue_exit_process(Process *p) if (dep) { erts_do_net_exits(dep, reason); - if(dep) - erts_deref_dist_entry(dep); } /* diff --git a/erts/emulator/beam/erl_process.h b/erts/emulator/beam/erl_process.h index 20ffe7ea7c..10c6fa4a67 100644 --- a/erts/emulator/beam/erl_process.h +++ b/erts/emulator/beam/erl_process.h @@ -801,12 +801,11 @@ erts_smp_reset_max_len(ErtsRunQueue *rq, ErtsRunQueueInfo *rqi) #define ERTS_PSD_ERROR_HANDLER 0 #define ERTS_PSD_SAVED_CALLS_BUF 1 #define ERTS_PSD_SCHED_ID 2 -#define ERTS_PSD_DIST_ENTRY 3 -#define ERTS_PSD_CALL_TIME_BP 4 -#define ERTS_PSD_DELAYED_GC_TASK_QS 5 -#define ERTS_PSD_NIF_TRAP_EXPORT 6 +#define ERTS_PSD_CALL_TIME_BP 3 +#define ERTS_PSD_DELAYED_GC_TASK_QS 4 +#define ERTS_PSD_NIF_TRAP_EXPORT 5 -#define ERTS_PSD_SIZE 7 +#define ERTS_PSD_SIZE 6 typedef struct { void *data[ERTS_PSD_SIZE]; @@ -824,9 +823,6 @@ typedef struct { #define ERTS_PSD_SCHED_ID_GET_LOCKS ERTS_PROC_LOCK_STATUS #define ERTS_PSD_SCHED_ID_SET_LOCKS ERTS_PROC_LOCK_STATUS -#define ERTS_PSD_DIST_ENTRY_GET_LOCKS ERTS_PROC_LOCK_MAIN -#define ERTS_PSD_DIST_ENTRY_SET_LOCKS ERTS_PROC_LOCK_MAIN - #define ERTS_PSD_CALL_TIME_BP_GET_LOCKS ERTS_PROC_LOCK_MAIN #define ERTS_PSD_CALL_TIME_BP_SET_LOCKS ERTS_PROC_LOCK_MAIN @@ -1887,11 +1883,6 @@ erts_psd_set(Process *p, ErtsProcLocks plocks, int ix, void *data) #define ERTS_PROC_SCHED_ID(P, L, ID) \ ((UWord) erts_psd_set((P), (L), ERTS_PSD_SCHED_ID, (void *) (ID))) -#define ERTS_PROC_GET_DIST_ENTRY(P) \ - ((DistEntry *) erts_psd_get((P), ERTS_PSD_DIST_ENTRY)) -#define ERTS_PROC_SET_DIST_ENTRY(P, L, D) \ - ((DistEntry *) erts_psd_set((P), (L), ERTS_PSD_DIST_ENTRY, (void *) (D))) - #define ERTS_PROC_GET_SAVED_CALLS_BUF(P) \ ((struct saved_calls *) erts_psd_get((P), ERTS_PSD_SAVED_CALLS_BUF)) #define ERTS_PROC_SET_SAVED_CALLS_BUF(P, L, SCB) \ diff --git a/erts/emulator/beam/external.c b/erts/emulator/beam/external.c index c6d7e3fcc5..a85aa15403 100644 --- a/erts/emulator/beam/external.c +++ b/erts/emulator/beam/external.c @@ -1179,7 +1179,7 @@ typedef struct { ErtsHeapFactory factory; int remaining_n; char* remaining_bytes; - Eterm* maps_list; + ErtsWStack flat_maps; ErtsPStack hamt_array; } B2TDecodeContext; @@ -1519,7 +1519,7 @@ static BIF_RETTYPE binary_to_term_int(Process* p, Uint32 flags, Eterm bin, Binar ctx->u.dc.res = (Eterm) (UWord) NULL; ctx->u.dc.next = &ctx->u.dc.res; erts_factory_proc_prealloc_init(&ctx->u.dc.factory, p, ctx->heap_size); - ctx->u.dc.maps_list = NULL; + ctx->u.dc.flat_maps.wstart = NULL; ctx->u.dc.hamt_array.pstart = NULL; ctx->state = B2TDecode; /*fall through*/ @@ -2938,7 +2938,7 @@ dec_term(ErtsDistExternal *edep, int n; ErtsAtomEncoding char_enc; register Eterm* hp; /* Please don't take the address of hp */ - Eterm *maps_list; /* for preprocessing of small maps */ + DECLARE_WSTACK(flat_maps); /* for preprocessing of small maps */ Eterm* next; SWord reds; #ifdef DEBUG @@ -2950,7 +2950,6 @@ dec_term(ErtsDistExternal *edep, next = ctx->u.dc.next; ep = ctx->u.dc.ep; factory = &ctx->u.dc.factory; - maps_list = ctx->u.dc.maps_list; if (ctx->state != B2TDecode) { int n_limit = reds; @@ -3026,15 +3025,18 @@ dec_term(ErtsDistExternal *edep, } } PSTACK_CHANGE_ALLOCATOR(hamt_array, ERTS_ALC_T_SAVED_ESTACK); + WSTACK_CHANGE_ALLOCATOR(flat_maps, ERTS_ALC_T_SAVED_ESTACK); if (ctx->u.dc.hamt_array.pstart) { PSTACK_RESTORE(hamt_array, &ctx->u.dc.hamt_array); } + if (ctx->u.dc.flat_maps.wstart) { + WSTACK_RESTORE(flat_maps, &ctx->u.dc.flat_maps); + } } else { reds = ERTS_SWORD_MAX; next = objp; *next = (Eterm) (UWord) NULL; - maps_list = NULL; } hp = factory->hp; @@ -3595,14 +3597,8 @@ dec_term_atom_common: * vptr, last word for values */ - /* - * Use thing_word to link through decoded maps. - * The list of maps is for later validation. - */ - - mp->thing_word = (Eterm) COMPRESS_POINTER(maps_list); - maps_list = (Eterm *) mp; - + WSTACK_PUSH(flat_maps, (UWord)mp); + mp->thing_word = MAP_HEADER_FLATMAP; mp->size = size; mp->keys = keys; *objp = make_flatmap(mp); @@ -3851,7 +3847,9 @@ dec_term_atom_common: ctx->u.dc.ep = ep; ctx->u.dc.next = next; ctx->u.dc.factory.hp = hp; - ctx->u.dc.maps_list = maps_list; + if (!WSTACK_ISEMPTY(flat_maps)) { + WSTACK_SAVE(flat_maps, &ctx->u.dc.flat_maps); + } if (!PSTACK_IS_EMPTY(hamt_array)) { PSTACK_SAVE(hamt_array, &ctx->u.dc.hamt_array); } @@ -3865,18 +3863,6 @@ dec_term_atom_common: } } - /* Iterate through all the maps and check for validity and sort keys - * - done here for when we know it is complete. - */ - - while (maps_list) { - next = (Eterm *)(EXPAND_POINTER(*maps_list)); - *maps_list = MAP_HEADER_FLATMAP; - if (!erts_validate_and_sort_flatmap((flatmap_t*)maps_list)) - goto error; - maps_list = next; - } - ASSERT(hp <= factory->hp_end || (factory->mode == FACTORY_CLOSED && is_immed(*dbg_resultp))); factory->hp = hp; @@ -3885,20 +3871,31 @@ dec_term_atom_common: */ if (!PSTACK_IS_EMPTY(hamt_array)) { - do { - struct dec_term_hamt* hamt = PSTACK_TOP(hamt_array); - - *hamt->objp = erts_hashmap_from_array(factory, - hamt->leaf_array, - hamt->size, - 1); - if (is_non_value(*hamt->objp)) - goto error_hamt; - - (void) PSTACK_POP(hamt_array); - } while (!PSTACK_IS_EMPTY(hamt_array)); - PSTACK_DESTROY(hamt_array); + do { + struct dec_term_hamt* hamt = PSTACK_TOP(hamt_array); + + *hamt->objp = erts_hashmap_from_array(factory, + hamt->leaf_array, + hamt->size, + 1); + if (is_non_value(*hamt->objp)) + goto error_hamt; + + (void) PSTACK_POP(hamt_array); + } while (!PSTACK_IS_EMPTY(hamt_array)); + PSTACK_DESTROY(hamt_array); + } + + /* Iterate through all the (flat)maps and check for validity and sort keys + * - done here for when we know it is complete. + */ + + while(!WSTACK_ISEMPTY(flat_maps)) { + next = (Eterm *)WSTACK_POP(flat_maps); + if (!erts_validate_and_sort_flatmap((flatmap_t*)next)) + goto error; } + WSTACK_DESTROY(flat_maps); ASSERT((Eterm*)EXPAND_POINTER(*dbg_resultp) != NULL); @@ -3924,6 +3921,7 @@ error_hamt: ctx->state = B2TDecodeFail; ctx->reds = reds; } + WSTACK_DESTROY(flat_maps); return NULL; } diff --git a/erts/emulator/beam/io.c b/erts/emulator/beam/io.c index 900616c981..c64c8802b9 100644 --- a/erts/emulator/beam/io.c +++ b/erts/emulator/beam/io.c @@ -7596,15 +7596,15 @@ int null_func(void) } int -erl_drv_putenv(char *key, char *value) +erl_drv_putenv(const char *key, char *value) { - return erts_sys_putenv_raw(key, value); + return erts_sys_putenv_raw((char*)key, value); } int -erl_drv_getenv(char *key, char *value, size_t *value_size) +erl_drv_getenv(const char *key, char *value, size_t *value_size) { - return erts_sys_getenv_raw(key, value, value_size); + return erts_sys_getenv_raw((char*)key, value, value_size); } /* get heart_port diff --git a/erts/emulator/beam/sys.h b/erts/emulator/beam/sys.h index bb871b05ba..ec94e3a596 100644 --- a/erts/emulator/beam/sys.h +++ b/erts/emulator/beam/sys.h @@ -634,7 +634,6 @@ Uint erts_sys_misc_mem_sz(void); /* Io constants to erts_print and erts_putc */ #define ERTS_PRINT_STDERR (2) #define ERTS_PRINT_STDOUT (1) -#define ERTS_PRINT_INVALID (0) /* Don't want to use 0 since CBUF was 0 */ #define ERTS_PRINT_FILE (-1) #define ERTS_PRINT_SBUF (-2) #define ERTS_PRINT_SNBUF (-3) diff --git a/erts/emulator/beam/utils.c b/erts/emulator/beam/utils.c index e9d7c91ac9..5286391746 100644 --- a/erts/emulator/beam/utils.c +++ b/erts/emulator/beam/utils.c @@ -399,9 +399,6 @@ erts_print(int to, void *arg, char *format, ...) case ERTS_PRINT_DSBUF: res = erts_vdsprintf((erts_dsprintf_buf_t *) arg, format, arg_list); break; - case ERTS_PRINT_INVALID: - res = -EINVAL; - break; default: res = erts_vfdprintf((int) to, format, arg_list); break; diff --git a/erts/emulator/drivers/common/efile_drv.c b/erts/emulator/drivers/common/efile_drv.c index 8aff6c1865..3b6abec25e 100644 --- a/erts/emulator/drivers/common/efile_drv.c +++ b/erts/emulator/drivers/common/efile_drv.c @@ -2581,7 +2581,6 @@ file_async_ready(ErlDrvData e, ErlDrvThreadData data) case FILE_CLOSE_ON_PORT_EXIT: /* See file_stop. However this is never invoked after the port is killed. */ free_data(data); - EF_FREE(desc); desc = NULL; /* This is it for this port, so just send dtrace and return, avoid doing anything to the freed data */ DTRACE6(efile_drv_return, sched_i1, sched_i2, sched_utag, diff --git a/erts/emulator/drivers/common/inet_drv.c b/erts/emulator/drivers/common/inet_drv.c index a829599fe5..89011d89ad 100644 --- a/erts/emulator/drivers/common/inet_drv.c +++ b/erts/emulator/drivers/common/inet_drv.c @@ -1,7 +1,7 @@ /* * %CopyrightBegin% * - * Copyright Ericsson AB 1997-2013. All Rights Reserved. + * Copyright Ericsson AB 1997-2015. All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -6076,9 +6076,9 @@ static int inet_set_opts(inet_descriptor* desc, char* ptr, int len) int arg_sz; enum PacketParseType old_htype = desc->htype; int old_active = desc->active; - int propagate = 0; /* Set to 1 if failure to set this option - should be propagated to erlang (not all - errors can be propagated for BC reasons) */ + int propagate; /* Set to 1 if failure to set this option + should be propagated to erlang (not all + errors can be propagated for BC reasons) */ int res; #ifdef HAVE_SCTP /* SCTP sockets are treated completely separately: */ @@ -6095,6 +6095,7 @@ static int inet_set_opts(inet_descriptor* desc, char* ptr, int len) arg_ptr = (char*) &ival; arg_sz = sizeof(ival); proto = SOL_SOCKET; + propagate = 0; switch(opt) { case INET_LOPT_HEADER: diff --git a/erts/emulator/hipe/hipe_x86_signal.c b/erts/emulator/hipe/hipe_x86_signal.c index bb8a3f041f..69d4ea10c2 100644 --- a/erts/emulator/hipe/hipe_x86_signal.c +++ b/erts/emulator/hipe/hipe_x86_signal.c @@ -198,7 +198,7 @@ static void do_init(void) #define INIT() do { if (!init_done()) do_init(); } while (0) #endif /* __DARWIN__ */ -#if !defined(__GLIBC__) && !defined(__DARWIN__) && !defined(__NetBSD__) +#if defined(__sun__) /* * Assume Solaris/x86 2.8. * There is a number of sigaction() procedures in libc: @@ -232,7 +232,34 @@ static void do_init(void) } #define _NSIG NSIG #define INIT() do { if (!init_done()) do_init(); } while (0) -#endif /* not glibc or darwin */ +#endif /* __sun__ */ + +#if !(defined(__GLIBC__) || defined(__DARWIN__) || defined(__NetBSD__) || defined(__sun__)) +/* + * Unknown libc -- assume musl. Note: musl deliberately does not provide a musl-specific + * feature test macro, so we cannot check for it. + * + * sigaction is a weak alias for __sigaction, which is a wrapper for __libc_sigaction. + * There are libc-internal calls to __libc_sigaction which install handlers, so we must + * override __libc_sigaction rather than __sigaction. + */ +#include <dlfcn.h> +static int (*__next_sigaction)(int, const struct sigaction*, struct sigaction*); +#define init_done() (__next_sigaction != 0) +#define __SIGACTION __libc_sigaction +static void do_init(void) +{ + __next_sigaction = dlsym(RTLD_NEXT, "__libc_sigaction"); + if (__next_sigaction != 0) + return; + perror("dlsym"); + abort(); +} +#ifndef _NSIG +#define _NSIG NSIG +#endif +#define INIT() do { if (!init_done()) do_init(); } while (0) +#endif /* !(__GLIBC__ || __DARWIN__ || __NetBSD__ || __sun__) */ #if !defined(__NetBSD__) /* diff --git a/erts/emulator/sys/win32/erl_win32_sys_ddll.c b/erts/emulator/sys/win32/erl_win32_sys_ddll.c index 9a5557e93d..7c24a77e31 100644 --- a/erts/emulator/sys/win32/erl_win32_sys_ddll.c +++ b/erts/emulator/sys/win32/erl_win32_sys_ddll.c @@ -52,7 +52,8 @@ void erl_sys_ddll_init(void) { #define ERL_NIF_API_FUNC_DECL(RET,NAME,ARGS) nif_callbacks.NAME = NAME #include "erl_nif_api_funcs.h" #undef ERL_NIF_API_FUNC_DECL - + nif_callbacks.erts_alc_test = erts_alc_test; + return; } diff --git a/erts/emulator/sys/win32/erl_win_dyn_driver.h b/erts/emulator/sys/win32/erl_win_dyn_driver.h index 5e62320be4..baac7c903e 100644 --- a/erts/emulator/sys/win32/erl_win_dyn_driver.h +++ b/erts/emulator/sys/win32/erl_win_dyn_driver.h @@ -145,8 +145,8 @@ WDD_TYPEDEF(ErlDrvTid, erl_drv_thread_self, (void)); WDD_TYPEDEF(int, erl_drv_equal_tids, (ErlDrvTid tid1, ErlDrvTid tid2)); WDD_TYPEDEF(void, erl_drv_thread_exit, (void *resp)); WDD_TYPEDEF(int, erl_drv_thread_join, (ErlDrvTid, void **respp)); -WDD_TYPEDEF(int, erl_drv_putenv, (char *key, char *value)); -WDD_TYPEDEF(int, erl_drv_getenv, (char *key, char *value, size_t *value_size)); +WDD_TYPEDEF(int, erl_drv_putenv, (const char *key, char *value)); +WDD_TYPEDEF(int, erl_drv_getenv, (const char *key, char *value, size_t *value_size)); typedef struct { WDD_FTYPE(null_func) *null_func; diff --git a/erts/emulator/test/alloc_SUITE.erl b/erts/emulator/test/alloc_SUITE.erl index 7c7ddde5d4..aa6a1fbcdc 100644 --- a/erts/emulator/test/alloc_SUITE.erl +++ b/erts/emulator/test/alloc_SUITE.erl @@ -31,7 +31,8 @@ rbtree/1, mseg_clear_cache/1, erts_mmap/1, - cpool/1]). + cpool/1, + migration/1]). -export([init_per_testcase/2, end_per_testcase/2]). @@ -43,7 +44,7 @@ suite() -> [{ct_hooks,[ts_install_cth]}]. all() -> [basic, coalesce, threads, realloc_copy, bucket_index, - bucket_mask, rbtree, mseg_clear_cache, erts_mmap, cpool]. + bucket_mask, rbtree, mseg_clear_cache, erts_mmap, cpool, migration]. groups() -> []. @@ -64,7 +65,7 @@ end_per_group(_GroupName, Config) -> init_per_testcase(Case, Config) when is_list(Config) -> Dog = ?t:timetrap(?t:seconds(?DEFAULT_TIMETRAP_SECS)), - [{watchdog, Dog},{testcase, Case}|Config]. + [{watchdog, Dog}, {testcase, Case}, {debug,false} | Config]. end_per_testcase(_Case, Config) when is_list(Config) -> Dog = ?config(watchdog, Config), @@ -112,6 +113,14 @@ cpool(suite) -> []; cpool(doc) -> []; cpool(Cfg) -> ?line drv_case(Cfg). +migration(Cfg) -> + case erlang:system_info(smp_support) of + true -> + drv_case(Cfg, concurrent, "+MZe true"); + false -> + {skipped, "No smp"} + end. + erts_mmap(Config) when is_list(Config) -> case {?t:os_type(), is_halfword_vm()} of {{unix, _}, false} -> @@ -176,18 +185,17 @@ erts_mmap_do(Config, SCO, SCRPM, SCRFSD) -> %% %% drv_case(Config) -> - drv_case(Config, ""). + drv_case(Config, one_shot, ""). -drv_case(Config, Command) when is_list(Config), - is_list(Command) -> +drv_case(Config, Mode, NodeOpts) when is_list(Config) -> case ?t:os_type() of {Family, _} when Family == unix; Family == win32 -> - ?line {ok, Node} = start_node(Config), + ?line {ok, Node} = start_node(Config, NodeOpts), ?line Self = self(), ?line Ref = make_ref(), ?line spawn_link(Node, fun () -> - Res = run_drv_case(Config, Command), + Res = run_drv_case(Config, Mode), Self ! {Ref, Res} end), ?line Result = receive {Ref, Rslt} -> Rslt end, @@ -199,49 +207,172 @@ drv_case(Config, Command) when is_list(Config), | io_lib:format("~p",[SkipOs])])} end. -run_drv_case(Config, Command) -> - ?line DataDir = ?config(data_dir,Config), - ?line CaseName = ?config(testcase,Config), - case erl_ddll:load_driver(DataDir, CaseName) of - ok -> ok; - {error, Error} -> - io:format("~s\n", [erl_ddll:format_error(Error)]), - ?line ?t:fail() +run_drv_case(Config, Mode) -> + DataDir = ?config(data_dir,Config), + CaseName = ?config(testcase,Config), + File = filename:join(DataDir, CaseName), + {ok,CaseName,Bin} = compile:file(File, [binary,return_errors]), + {module,CaseName} = erlang:load_module(CaseName,Bin), + print_stats(CaseName), + ok = CaseName:init(File), + + SlaveState = slave_init(CaseName), + case Mode of + one_shot -> + Result = one_shot(CaseName); + + concurrent -> + Result = concurrent(CaseName) end, - ?line Port = open_port({spawn, atom_to_list(CaseName)}, []), - ?line true = is_port(Port), - ?line Port ! {self(), {command, Command}}, - ?line Result = receive_drv_result(Port, CaseName), - ?line Port ! {self(), close}, - ?line receive - {Port, closed} -> - ok - end, - ?line ok = erl_ddll:unload_driver(CaseName), - ?line Result. - -receive_drv_result(Port, CaseName) -> - ?line receive - {print, Port, CaseName, Str} -> - ?line ?t:format("~s", [Str]), - ?line receive_drv_result(Port, CaseName); - {'EXIT', Port, Error} -> - ?line ?t:fail(Error); - {'EXIT', error, Error} -> - ?line ?t:fail(Error); - {failed, Port, CaseName, Comment} -> - ?line ?t:fail(Comment); - {skipped, Port, CaseName, Comment} -> - ?line {skipped, Comment}; - {succeeded, Port, CaseName, ""} -> - ?line succeeded; - {succeeded, Port, CaseName, Comment} -> - ?line {comment, Comment} - end. - -start_node(Config) -> - start_node(Config, []). + + wait_for_memory_deallocations(), + print_stats(CaseName), + + true = erlang:delete_module(CaseName), + slave_end(SlaveState), + Result. + +slave_init(migration) -> + A0 = case application:start(sasl) of + ok -> [sasl]; + _ -> [] + end, + case application:start(os_mon) of + ok -> [os_mon|A0]; + _ -> A0 + end; +slave_init(_) -> []. + +slave_end(Apps) -> + lists:foreach(fun (A) -> application:stop(A) end, Apps). + +wait_for_memory_deallocations() -> + try + erts_debug:set_internal_state(wait, deallocations) + catch + error:undef -> + erts_debug:set_internal_state(available_internal_state, true), + wait_for_memory_deallocations() + end. + +print_stats(migration) -> + {Btot,Ctot} = lists:foldl(fun({instance,Inr,Istats}, {Bacc,Cacc}) -> + {mbcs,MBCS} = lists:keyfind(mbcs, 1, Istats), + Btup = lists:keyfind(blocks, 1, MBCS), + Ctup = lists:keyfind(carriers, 1, MBCS), + io:format("{instance,~p,~p,~p}\n", [Inr, Btup, Ctup]), + {tuple_add(Bacc,Btup),tuple_add(Cacc,Ctup)}; + (_, Acc) -> Acc + end, + {{blocks,0,0,0},{carriers,0,0,0}}, + erlang:system_info({allocator,test_alloc})), + + io:format("Number of blocks : ~p\n", [Btot]), + io:format("Number of carriers: ~p\n", [Ctot]); + +print_stats(_) -> ok. + +tuple_add(T1, T2) -> + list_to_tuple(lists:zipwith(fun(E1,E2) when is_number(E1), is_number(E2) -> + E1 + E2; + (A,A) -> + A + end, + tuple_to_list(T1), tuple_to_list(T2))). + + +one_shot(CaseName) -> + State = CaseName:start({1, 0, erlang:system_info(build_type)}), + Result0 = CaseName:run(State), + false = (Result0 =:= continue), + Result1 = handle_result(State, Result0), + CaseName:stop(State), + Result1. + + +many_shot(CaseName, I, Mem) -> + State = CaseName:start({I, Mem, erlang:system_info(build_type)}), + Result1 = repeat_while(fun() -> + Result0 = CaseName:run(State), + handle_result(State, Result0) + end, + 10*1000, I), + CaseName:stop(State), + flush_log(), + Result1. + +concurrent(CaseName) -> + NSched = erlang:system_info(schedulers), + Mem = (free_memory() * 3) div 4, + PRs = lists:map(fun(I) -> spawn_opt(fun() -> + many_shot(CaseName, I, + Mem div NSched) + end, + [monitor, {scheduler,I}]) + end, + lists:seq(1, NSched)), + lists:foreach(fun({Pid,Ref}) -> + receive {'DOWN', Ref, process, Pid, Reason} -> + Reason + end + end, + PRs), + ok. + +repeat_while(Fun, Timeout, I) -> + TRef = erlang:start_timer(Timeout, self(), timeout), + R = repeat_while_loop(Fun, TRef, I), + erlang:cancel_timer(TRef, [{async,true},{info,false}]), + R. + +repeat_while_loop(Fun, TRef, I) -> + receive + {timeout, TRef, timeout} -> + io:format("~p: Timeout, enough is enough.",[I]), + succeeded + after 0 -> + %%io:format("~p calls fun\n", [self()]), + case Fun() of + continue -> repeat_while_loop(Fun, TRef, I); + R -> R + end + end. + +flush_log() -> + receive + {print, Str} -> + ?t:format("~s", [Str]), + flush_log() + after 0 -> + ok + end. + +handle_result(_State, Result0) -> + flush_log(), + case Result0 of + {'EXIT', Error} -> + ?line ?t:fail(Error); + {'EXIT', error, Error} -> + ?line ?t:fail(Error); + {failed, Comment} -> + ?line ?t:fail(Comment); + {skipped, Comment} -> + ?line {skipped, Comment}; + {succeeded, ""} -> + ?line succeeded; + {succeeded, Comment} -> + ?line {comment, Comment}; + continue -> + continue + end. + start_node(Config, Opts) when is_list(Config), is_list(Opts) -> + case ?config(debug,Config) of + true -> {ok, node()}; + _ -> start_node_1(Config, Opts) + end. + +start_node_1(Config, Opts) -> Pa = filename:dirname(code:which(?MODULE)), Name = list_to_atom(atom_to_list(?MODULE) ++ "-" @@ -252,6 +383,7 @@ start_node(Config, Opts) when is_list(Config), is_list(Opts) -> ++ integer_to_list(erlang:unique_integer([positive]))), ?t:start_node(Name, slave, [{args, Opts++" -pa "++Pa}]). +stop_node(Node) when Node =:= node() -> ok; stop_node(Node) -> ?t:stop_node(Node). @@ -261,3 +393,23 @@ is_halfword_vm() -> {4, 8} -> true; {WS, WS} -> false end. + +free_memory() -> + %% Free memory in MB. + try + SMD = memsup:get_system_memory_data(), + {value, {free_memory, Free}} = lists:keysearch(free_memory, 1, SMD), + TotFree = (Free + + case lists:keysearch(cached_memory, 1, SMD) of + {value, {cached_memory, Cached}} -> Cached; + false -> 0 + end + + case lists:keysearch(buffered_memory, 1, SMD) of + {value, {buffered_memory, Buffed}} -> Buffed; + false -> 0 + end), + TotFree div (1024*1024) + catch + error : undef -> + ?t:fail({"os_mon not built"}) + end. diff --git a/erts/emulator/test/alloc_SUITE_data/Makefile.src b/erts/emulator/test/alloc_SUITE_data/Makefile.src index a441fe946b..e31de54e1b 100644 --- a/erts/emulator/test/alloc_SUITE_data/Makefile.src +++ b/erts/emulator/test/alloc_SUITE_data/Makefile.src @@ -25,7 +25,8 @@ TEST_DRVS = basic@dll@ \ bucket_mask@dll@ \ rbtree@dll@ \ mseg_clear_cache@dll@ \ - cpool@dll@ + cpool@dll@ \ + migration@dll@ CC = @CC@ LD = @LD@ diff --git a/erts/emulator/test/alloc_SUITE_data/allocator_test.h b/erts/emulator/test/alloc_SUITE_data/allocator_test.h index 1d6b2f4907..97ee58cdad 100644 --- a/erts/emulator/test/alloc_SUITE_data/allocator_test.h +++ b/erts/emulator/test/alloc_SUITE_data/allocator_test.h @@ -20,9 +20,20 @@ #ifndef ALLOCATOR_TEST_H__ #define ALLOCATOR_TEST_H__ -typedef ErlDrvUInt Ulong; +#if SIZEOF_VOID_P == SIZEOF_INT +typedef unsigned int Ulong; +#elif SIZEOF_VOID_P == SIZEOF_LONG +typedef unsigned long Ulong; +#elif SIZEOF_VOID_P == SIZEOF_LONG_LONG +typedef unsigned long long Ulong; +#else +# error No pointer sized integer type found ??? +#endif -#ifndef __WIN32__ +#ifdef __WIN32__ +typedef Ulong erts_alc_test_Fn(Ulong, Ulong, Ulong, Ulong); +# define erts_alc_test ((erts_alc_test_Fn*)WinDynNifCallbacks.erts_alc_test) +#else Ulong erts_alc_test(Ulong, Ulong, Ulong, Ulong); #endif @@ -85,6 +96,7 @@ typedef void* erts_cond; #define CPOOL_DELETE(A,B) ((Carrier_t *) ALC_TEST2(0x022, (A), (B))) #define CPOOL_IS_EMPTY(A) ((int) ALC_TEST1(0x023, (A))) #define CPOOL_IS_IN_POOL(A,B) ((int) ALC_TEST2(0x024, (A), (B))) +#define UMEM2BLK_TEST(P) ((Block_t*) ALC_TEST1(0x025, (P))) /* From erl_goodfit_alloc.c */ #define BKT_IX(A, S) ((Ulong) ALC_TEST2(0x100, (A), (S))) @@ -142,5 +154,9 @@ typedef void* erts_cond; #define THR_JOIN(T) ((void) ALC_TEST1(0xf11, (T))) #define THR_EXIT(R) ((void) ALC_TEST1(0xf12, (R))) #define IS_SMP_ENABLED ((int) ALC_TEST0(0xf13)) +#define ALLOC_TEST(S) ((void*) ALC_TEST1(0xf14, (S))) +#define FREE_TEST(P) ((void) ALC_TEST1(0xf15, (P))) +#define SET_TEST_MBC_USER_HEADER(SZ,CMBC,DMBC) ((int)ALC_TEST3(0xf16, (SZ), (CMBC), (DMBC))) +#define GET_TEST_MBC_SIZE() ((int) ALC_TEST0(0xf17)) #endif diff --git a/erts/emulator/test/alloc_SUITE_data/basic.c b/erts/emulator/test/alloc_SUITE_data/basic.c index 323a24a11f..debb3d7ebe 100644 --- a/erts/emulator/test/alloc_SUITE_data/basic.c +++ b/erts/emulator/test/alloc_SUITE_data/basic.c @@ -60,3 +60,6 @@ testcase_cleanup(TestCaseState_t *tcs) if (tcs->extra) STOP_ALC((Allctr_t *) tcs->extra); } + +ERL_NIF_INIT(basic, testcase_nif_funcs, testcase_nif_init, + NULL, NULL, NULL); diff --git a/erts/emulator/test/alloc_SUITE_data/basic.erl b/erts/emulator/test/alloc_SUITE_data/basic.erl new file mode 100644 index 0000000000..a018fd5582 --- /dev/null +++ b/erts/emulator/test/alloc_SUITE_data/basic.erl @@ -0,0 +1,10 @@ +-module(basic). + +-export([init/1, start/1, run/1, stop/1]). + +init(File) -> + ok = erlang:load_nif(File, 0). + +start(_) -> erlang:nif_error(not_loaded). +run(_) -> erlang:nif_error(not_loaded). +stop(_) -> erlang:nif_error(not_loaded). diff --git a/erts/emulator/test/alloc_SUITE_data/bucket_index.c b/erts/emulator/test/alloc_SUITE_data/bucket_index.c index c13f229049..45cb53fbf7 100644 --- a/erts/emulator/test/alloc_SUITE_data/bucket_index.c +++ b/erts/emulator/test/alloc_SUITE_data/bucket_index.c @@ -113,3 +113,5 @@ test_it(TestCaseState_t *tcs, unsigned sbct) sbct ? sbct_buf : "default"); } +ERL_NIF_INIT(bucket_index, testcase_nif_funcs, testcase_nif_init, + NULL, NULL, NULL); diff --git a/erts/emulator/test/alloc_SUITE_data/bucket_index.erl b/erts/emulator/test/alloc_SUITE_data/bucket_index.erl new file mode 100644 index 0000000000..c54f54e2f5 --- /dev/null +++ b/erts/emulator/test/alloc_SUITE_data/bucket_index.erl @@ -0,0 +1,10 @@ +-module(bucket_index). + +-export([init/1, start/1, run/1, stop/1]). + +init(File) -> + ok = erlang:load_nif(File, 0). + +start(_) -> erlang:nif_error(not_loaded). +run(_) -> erlang:nif_error(not_loaded). +stop(_) -> erlang:nif_error(not_loaded). diff --git a/erts/emulator/test/alloc_SUITE_data/bucket_mask.c b/erts/emulator/test/alloc_SUITE_data/bucket_mask.c index 8d6166771e..c94c265f4e 100644 --- a/erts/emulator/test/alloc_SUITE_data/bucket_mask.c +++ b/erts/emulator/test/alloc_SUITE_data/bucket_mask.c @@ -52,7 +52,7 @@ testcase_run(TestCaseState_t *tcs) typedef struct linked_block { struct linked_block* next; }Linked; - Linked* link; + Linked* link = NULL; Linked* fence_list; Linked* pad_list; void* tmp; @@ -183,3 +183,5 @@ testcase_run(TestCaseState_t *tcs) tcs->extra = NULL; } +ERL_NIF_INIT(bucket_mask, testcase_nif_funcs, testcase_nif_init, + NULL, NULL, NULL); diff --git a/erts/emulator/test/alloc_SUITE_data/bucket_mask.erl b/erts/emulator/test/alloc_SUITE_data/bucket_mask.erl new file mode 100644 index 0000000000..589a50e1fa --- /dev/null +++ b/erts/emulator/test/alloc_SUITE_data/bucket_mask.erl @@ -0,0 +1,10 @@ +-module(bucket_mask). + +-export([init/1, start/1, run/1, stop/1]). + +init(File) -> + ok = erlang:load_nif(File, 0). + +start(_) -> erlang:nif_error(not_loaded). +run(_) -> erlang:nif_error(not_loaded). +stop(_) -> erlang:nif_error(not_loaded). diff --git a/erts/emulator/test/alloc_SUITE_data/coalesce.c b/erts/emulator/test/alloc_SUITE_data/coalesce.c index 0a5e0c5b0e..7791409a34 100644 --- a/erts/emulator/test/alloc_SUITE_data/coalesce.c +++ b/erts/emulator/test/alloc_SUITE_data/coalesce.c @@ -317,3 +317,6 @@ testcase_cleanup(TestCaseState_t *tcs) if (tcs->extra) STOP_ALC((Allctr_t *) tcs->extra); } + +ERL_NIF_INIT(coalesce, testcase_nif_funcs, testcase_nif_init, + NULL, NULL, NULL); diff --git a/erts/emulator/test/alloc_SUITE_data/coalesce.erl b/erts/emulator/test/alloc_SUITE_data/coalesce.erl new file mode 100644 index 0000000000..453c726c4e --- /dev/null +++ b/erts/emulator/test/alloc_SUITE_data/coalesce.erl @@ -0,0 +1,10 @@ +-module(coalesce). + +-export([init/1, start/1, run/1, stop/1]). + +init(File) -> + ok = erlang:load_nif(File, 0). + +start(_) -> erlang:nif_error(not_loaded). +run(_) -> erlang:nif_error(not_loaded). +stop(_) -> erlang:nif_error(not_loaded). diff --git a/erts/emulator/test/alloc_SUITE_data/cpool.c b/erts/emulator/test/alloc_SUITE_data/cpool.c index 75c2bc13ae..73026cc758 100644 --- a/erts/emulator/test/alloc_SUITE_data/cpool.c +++ b/erts/emulator/test/alloc_SUITE_data/cpool.c @@ -86,13 +86,13 @@ thread_func(void *arg) for (i = 0; i < (TEST_NO_CARRIERS_PER_THREAD+TEST_CARRIERS_OFFSET); i++) { int d; if (i < TEST_NO_CARRIERS_PER_THREAD) { - CPOOL_INSERT(alloc, crr[i]); + (void) CPOOL_INSERT(alloc, crr[i]); if ((i & 0x7) == 0) FATAL_ASSERT(CPOOL_IS_IN_POOL(alloc, crr[i])); } d = i-TEST_CARRIERS_OFFSET; if (d >= 0) { - CPOOL_DELETE(alloc, crr[d]); + (void) CPOOL_DELETE(alloc, crr[d]); if ((d & 0x7) == 0) FATAL_ASSERT(!CPOOL_IS_IN_POOL(alloc, crr[d])); } @@ -129,7 +129,7 @@ testcase_run(TestCaseState_t *tcs) for (c = 0; c < TEST_NO_CARRIERS_PER_THREAD; c++) { Carrier_t *crr = (Carrier_t *) p; p += zcrr_sz; - ZERO_CRR_INIT(alloc, crr); + (void) ZERO_CRR_INIT(alloc, crr); threads[t].crr[c] = crr; } } @@ -156,3 +156,6 @@ testcase_run(TestCaseState_t *tcs) ASSERT(tcs, no_threads == TEST_NO_THREADS); } + +ERL_NIF_INIT(cpool, testcase_nif_funcs, testcase_nif_init, + NULL, NULL, NULL); diff --git a/erts/emulator/test/alloc_SUITE_data/cpool.erl b/erts/emulator/test/alloc_SUITE_data/cpool.erl new file mode 100644 index 0000000000..89053471fa --- /dev/null +++ b/erts/emulator/test/alloc_SUITE_data/cpool.erl @@ -0,0 +1,10 @@ +-module(cpool). + +-export([init/1, start/1, run/1, stop/1]). + +init(File) -> + ok = erlang:load_nif(File, 0). + +start(_) -> erlang:nif_error(not_loaded). +run(_) -> erlang:nif_error(not_loaded). +stop(_) -> erlang:nif_error(not_loaded). diff --git a/erts/emulator/test/alloc_SUITE_data/migration.c b/erts/emulator/test/alloc_SUITE_data/migration.c new file mode 100644 index 0000000000..b006360043 --- /dev/null +++ b/erts/emulator/test/alloc_SUITE_data/migration.c @@ -0,0 +1,343 @@ +/* + * %CopyrightBegin% + * + * Copyright Ericsson AB 2014. All Rights Reserved. + * + * The contents of this file are subject to the Erlang Public License, + * Version 1.1, (the "License"); you may not use this file except in + * compliance with the License. You should have received a copy of the + * Erlang Public License along with this software. If not, it can be + * retrieved online at http://www.erlang.org/. + * + * Software distributed under the License is distributed on an "AS IS" + * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + * the License for the specific language governing rights and limitations + * under the License. + * + * %CopyrightEnd% + */ + +/* + * Test the carrier migration logic + */ + +#ifndef __WIN32__ +#include <sys/types.h> +#include <unistd.h> +#include <errno.h> +#endif +#include <stdio.h> +#include <stdlib.h> +#include <stdarg.h> +#include <string.h> +#include "testcase_driver.h" +#include "allocator_test.h" + +#define FATAL_ASSERT(A) \ + ((void) ((A) \ + ? 1 \ + : (fatal_assert_failed(#A, \ + (char *) __FILE__, \ + __LINE__), \ + 0))) + +static void +fatal_assert_failed(char* expr, char* file, int line) +{ + fflush(stdout); + fprintf(stderr, "%s:%d: Assertion failed: %s\n", + file, line, expr); + fflush(stderr); + abort(); +} + + +char * +testcase_name(void) +{ + return "migration"; +} + +/* Turns out random_r() is a nonstandard glibc extension. +#define HAVE_RANDOM_R +*/ +#ifdef HAVE_RANDOM_R + +typedef struct { struct random_data rnd; char rndbuf[32]; } MyRandState; + +static void myrand_init(MyRandState* mrs, unsigned int seed) +{ + int res; + memset(&mrs->rnd, 0, sizeof(mrs->rnd)); + res = initstate_r(seed, mrs->rndbuf, sizeof(mrs->rndbuf), &mrs->rnd); + FATAL_ASSERT(res == 0); +} + +static int myrand(MyRandState* mrs) +{ + int32_t x; + int res = random_r(&mrs->rnd, &x); + FATAL_ASSERT(res == 0); + return (int)x; +} + +#else /* !HAVE_RANDOM_R */ + +typedef unsigned int MyRandState; + +static void myrand_init(MyRandState* mrs, unsigned int seed) +{ + *mrs = seed; +} + +static int myrand(MyRandState* mrs) +{ + /* Taken from rand(3) man page. + * Modified to return a full 31-bit value by using low half of *mrs as well. + */ + *mrs = (*mrs) * 1103515245 + 12345; + return (int) (((*mrs >> 16) | (*mrs << 16)) & ~(1 << 31)); +} + +#endif /* !HAVE_RANDOM_R */ + +#define MAX_BLOCK_PER_THR 200 +#define BLOCKS_PER_MBC 10 +#define MAX_ROUNDS 10000 + +typedef struct MyBlock_ { + struct MyBlock_* next; + struct MyBlock_** prevp; +} MyBlock; + +typedef struct { + MyBlock* blockv[MAX_BLOCK_PER_THR]; + MyRandState rand_state; + enum { GROWING, SHRINKING, CLEANUP, DONE } phase; + int nblocks; + int goal_nblocks; + int round; + int nr_of_migrations; + int nr_of_carriers; + int max_blocks_in_mbc; + int block_size; + int max_nblocks; +} MigrationState; + +typedef struct { + ErlNifMutex* mtx; + int nblocks; + MyBlock* first; + MigrationState* employer; +} MyCrrInfo; + + +static int crr_info_offset = -1; +static void (*orig_create_mbc_fn)(Allctr_t *allctr, Carrier_t *carrier); +static void (*orig_destroying_mbc_fn)(Allctr_t *allctr, Carrier_t *carrier); + +static void my_creating_mbc(Allctr_t *allctr, Carrier_t *carrier) +{ + MyCrrInfo* mci = (MyCrrInfo*) ((char*)carrier + crr_info_offset); + if (orig_create_mbc_fn) + orig_create_mbc_fn(allctr, carrier); + + mci->mtx = enif_mutex_create("alloc_SUITE.migration"); + mci->nblocks = 0; + mci->first = NULL; + mci->employer = NULL; +} + +static void my_destroying_mbc(Allctr_t *allctr, Carrier_t *carrier) +{ + MyCrrInfo* mci = (MyCrrInfo*) ((char*)carrier + crr_info_offset); + + FATAL_ASSERT(mci->nblocks == 0); + FATAL_ASSERT(mci->first == NULL); + enif_mutex_destroy(mci->mtx); + + if (orig_destroying_mbc_fn) + orig_destroying_mbc_fn(allctr, carrier); +} + +static int migration_init(ErlNifEnv* env, void** priv_data, ERL_NIF_TERM load_info) +{ + void* creating_mbc_arg = (void*)my_creating_mbc; + void* destroying_mbc_arg = (void*)my_destroying_mbc; + + if (testcase_nif_init(env, priv_data, load_info)) + return -1; + + crr_info_offset = SET_TEST_MBC_USER_HEADER(sizeof(MyCrrInfo), + &creating_mbc_arg, + &destroying_mbc_arg); + FATAL_ASSERT(crr_info_offset >= 0); + orig_create_mbc_fn = creating_mbc_arg; + orig_destroying_mbc_fn = destroying_mbc_arg; + + return 0; +} + +static void add_block(MyBlock* p, MigrationState* state) +{ + MyCrrInfo* mci = (MyCrrInfo*)((char*)BLK_TO_MBC(UMEM2BLK_TEST(p)) + crr_info_offset); + + enif_mutex_lock(mci->mtx); + if (++mci->nblocks > state->max_blocks_in_mbc) + state->max_blocks_in_mbc = mci->nblocks; + p->next = mci->first; + p->prevp = &mci->first; + mci->first = p; + if (p->next) + p->next->prevp = &p->next; + if (mci->employer != state) { + if (!mci->employer) { + FATAL_ASSERT(mci->nblocks == 1); + state->nr_of_carriers++; + } + else { + state->nr_of_migrations++; + } + mci->employer = state; + } + enif_mutex_unlock(mci->mtx); +} + +static void remove_block(MyBlock* p) +{ + MyCrrInfo* mci = (MyCrrInfo*)((char*)BLK_TO_MBC(UMEM2BLK_TEST(p)) + crr_info_offset); + + enif_mutex_lock(mci->mtx); + mci->nblocks--; + if (p->next) + p->next->prevp = p->prevp; + *p->prevp = p->next; + enif_mutex_unlock(mci->mtx); +} + +static int rand_int(MigrationState* state, int low, int high) +{ + int x; + FATAL_ASSERT(high >= low); + x = myrand(&state->rand_state); + return low + (x % (high+1-low)); +} + + +static void do_cleanup(TestCaseState_t *tcs, MigrationState* state) +{ + if (state->nblocks == 0) { + state->phase = DONE; + testcase_printf(tcs, "%d: Done %d rounds", tcs->thr_nr, state->round); + testcase_printf(tcs, "%d: Cleanup all blocks", tcs->thr_nr); + testcase_printf(tcs, "%d: Empty carriers detected = %d", tcs->thr_nr, + state->nr_of_carriers); + testcase_printf(tcs, "%d: Migrations detected = %d", tcs->thr_nr, + state->nr_of_migrations); + testcase_printf(tcs, "%d: Max blocks in carrier = %d", tcs->thr_nr, + state->max_blocks_in_mbc); + } + else { + state->nblocks--; + if (state->blockv[state->nblocks]) { + remove_block(state->blockv[state->nblocks]); + FREE_TEST(state->blockv[state->nblocks]); + } + } +} + + +void +testcase_run(TestCaseState_t *tcs) +{ + MigrationState* state = (MigrationState*) tcs->extra; + + if (!tcs->extra) { + if (!IS_SMP_ENABLED) + testcase_skipped(tcs, "No SMP support"); + + tcs->extra = enif_alloc(sizeof(MigrationState)); + state = (MigrationState*) tcs->extra; + memset(state->blockv, 0, sizeof(state->blockv)); + myrand_init(&state->rand_state, tcs->thr_nr); + state->phase = GROWING; + state->nblocks = 0; + state->round = 0; + state->nr_of_migrations = 0; + state->nr_of_carriers = 0; + state->max_blocks_in_mbc = 0; + state->block_size = GET_TEST_MBC_SIZE() / (BLOCKS_PER_MBC+1); + if (MAX_BLOCK_PER_THR * state->block_size < tcs->free_mem) { + state->max_nblocks = MAX_BLOCK_PER_THR; + } else { + state->max_nblocks = tcs->free_mem / state->block_size; + } + state->goal_nblocks = rand_int(state, 1, state->max_nblocks); + } + + switch (state->phase) { + case GROWING: { + MyBlock* p; + FATAL_ASSERT(!state->blockv[state->nblocks]); + p = ALLOC_TEST(rand_int(state, state->block_size/2, state->block_size)); + FATAL_ASSERT(p); + add_block(p, state); + state->blockv[state->nblocks] = p; + if (++state->nblocks >= state->goal_nblocks) { + /*testcase_printf(tcs, "%d: Grown to %d blocks", tcs->thr_nr, state->nblocks);*/ + state->phase = SHRINKING; + state->goal_nblocks = rand_int(state, 0, state->goal_nblocks-1); + } + else + FATAL_ASSERT(!state->blockv[state->nblocks]); + break; + } + case SHRINKING: { + int ix = rand_int(state, 0, state->nblocks-1); + FATAL_ASSERT(state->blockv[ix]); + remove_block(state->blockv[ix]); + FREE_TEST(state->blockv[ix]); + state->blockv[ix] = state->blockv[--state->nblocks]; + state->blockv[state->nblocks] = NULL; + + if (state->nblocks <= state->goal_nblocks) { + /*testcase_printf(tcs, "%d: Shrunk to %d blocks", tcs->thr_nr, state->nblocks);*/ + if (++state->round >= MAX_ROUNDS) { + state->phase = CLEANUP; + } else { + state->phase = GROWING; + state->goal_nblocks = rand_int(state, state->goal_nblocks+1, state->max_nblocks); + } + } + break; + } + case CLEANUP: + do_cleanup(tcs, state); + break; + + default: + FATAL_ASSERT(!"Invalid phase"); + } + + if (state->phase == DONE) { + } + else { + testcase_continue(tcs); + } +} + +void +testcase_cleanup(TestCaseState_t *tcs) +{ + MigrationState* state = (MigrationState*) tcs->extra; + + while (state->phase != DONE) + do_cleanup(tcs, state); + + enif_free(tcs->extra); + tcs->extra = NULL; +} + + +ERL_NIF_INIT(migration, testcase_nif_funcs, migration_init, + NULL, NULL, NULL); diff --git a/erts/emulator/test/alloc_SUITE_data/migration.erl b/erts/emulator/test/alloc_SUITE_data/migration.erl new file mode 100644 index 0000000000..440a99becd --- /dev/null +++ b/erts/emulator/test/alloc_SUITE_data/migration.erl @@ -0,0 +1,10 @@ +-module(migration). + +-export([init/1, start/1, run/1, stop/1]). + +init(File) -> + ok = erlang:load_nif(File, 0). + +start(_) -> erlang:nif_error(not_loaded). +run(_) -> erlang:nif_error(not_loaded). +stop(_) -> erlang:nif_error(not_loaded). diff --git a/erts/emulator/test/alloc_SUITE_data/mseg_clear_cache.c b/erts/emulator/test/alloc_SUITE_data/mseg_clear_cache.c index 9c03f3a331..e5df3d647f 100644 --- a/erts/emulator/test/alloc_SUITE_data/mseg_clear_cache.c +++ b/erts/emulator/test/alloc_SUITE_data/mseg_clear_cache.c @@ -101,3 +101,6 @@ testcase_cleanup(TestCaseState_t *tcs) tcs->extra = NULL; } } + +ERL_NIF_INIT(mseg_clear_cache, testcase_nif_funcs, testcase_nif_init, + NULL, NULL, NULL); diff --git a/erts/emulator/test/alloc_SUITE_data/mseg_clear_cache.erl b/erts/emulator/test/alloc_SUITE_data/mseg_clear_cache.erl new file mode 100644 index 0000000000..befd6c2e8e --- /dev/null +++ b/erts/emulator/test/alloc_SUITE_data/mseg_clear_cache.erl @@ -0,0 +1,10 @@ +-module(mseg_clear_cache). + +-export([init/1, start/1, run/1, stop/1]). + +init(File) -> + ok = erlang:load_nif(File, 0). + +start(_) -> erlang:nif_error(not_loaded). +run(_) -> erlang:nif_error(not_loaded). +stop(_) -> erlang:nif_error(not_loaded). diff --git a/erts/emulator/test/alloc_SUITE_data/rbtree.c b/erts/emulator/test/alloc_SUITE_data/rbtree.c index 8d4d5535a8..38bbbdf90c 100644 --- a/erts/emulator/test/alloc_SUITE_data/rbtree.c +++ b/erts/emulator/test/alloc_SUITE_data/rbtree.c @@ -20,7 +20,7 @@ #include "testcase_driver.h" #include "allocator_test.h" -#define NO_BLOCKS 100000 +int NO_BLOCKS; #define RIGHT_VISITED (1 << 0) #define LEFT_VISITED (1 << 1) @@ -265,9 +265,10 @@ check_tree(TestCaseState_t *tcs, Allctr_t *alc, Ulong size) ASSERT(tcs, curr_blacks == 0); ASSERT(tcs, i == -1); + /* testcase_printf(tcs, "Red-Black Tree OK! Max depth = %d; " "Black depth = %d\n", max_i+1, blacks < 0 ? 0 : blacks); - + */ return res; } @@ -468,6 +469,12 @@ testcase_run(TestCaseState_t *tcs) Allctr_t *a; rbtree_test_data *td; + NO_BLOCKS = 100*1000; + if (enif_is_identical(tcs->build_type, + enif_make_atom(tcs->curr_env,"valgrind"))) { + NO_BLOCKS /= 10; + } + /* Best fit... */ testcase_printf(tcs, "Setup...\n"); @@ -577,3 +584,6 @@ testcase_run(TestCaseState_t *tcs) testcase_printf(tcs, "aoffcaobf test succeeded!\n"); } + +ERL_NIF_INIT(rbtree, testcase_nif_funcs, testcase_nif_init, + NULL, NULL, NULL); diff --git a/erts/emulator/test/alloc_SUITE_data/rbtree.erl b/erts/emulator/test/alloc_SUITE_data/rbtree.erl new file mode 100644 index 0000000000..f5b7120ff2 --- /dev/null +++ b/erts/emulator/test/alloc_SUITE_data/rbtree.erl @@ -0,0 +1,10 @@ +-module(rbtree). + +-export([init/1, start/1, run/1, stop/1]). + +init(File) -> + ok = erlang:load_nif(File, 0). + +start(_) -> erlang:nif_error(not_loaded). +run(_) -> erlang:nif_error(not_loaded). +stop(_) -> erlang:nif_error(not_loaded). diff --git a/erts/emulator/test/alloc_SUITE_data/realloc_copy.c b/erts/emulator/test/alloc_SUITE_data/realloc_copy.c index e405f06225..c4147eb00d 100644 --- a/erts/emulator/test/alloc_SUITE_data/realloc_copy.c +++ b/erts/emulator/test/alloc_SUITE_data/realloc_copy.c @@ -278,3 +278,5 @@ testcase_cleanup(TestCaseState_t *tcs) STOP_ALC((Allctr_t *) tcs->extra); } +ERL_NIF_INIT(realloc_copy, testcase_nif_funcs, testcase_nif_init, + NULL, NULL, NULL); diff --git a/erts/emulator/test/alloc_SUITE_data/realloc_copy.erl b/erts/emulator/test/alloc_SUITE_data/realloc_copy.erl new file mode 100644 index 0000000000..cc6617bf64 --- /dev/null +++ b/erts/emulator/test/alloc_SUITE_data/realloc_copy.erl @@ -0,0 +1,10 @@ +-module(realloc_copy). + +-export([init/1, start/1, run/1, stop/1]). + +init(File) -> + ok = erlang:load_nif(File, 0). + +start(_) -> erlang:nif_error(not_loaded). +run(_) -> erlang:nif_error(not_loaded). +stop(_) -> erlang:nif_error(not_loaded). diff --git a/erts/emulator/test/alloc_SUITE_data/testcase_driver.c b/erts/emulator/test/alloc_SUITE_data/testcase_driver.c index bc674c56b7..7dcca544e5 100644 --- a/erts/emulator/test/alloc_SUITE_data/testcase_driver.c +++ b/erts/emulator/test/alloc_SUITE_data/testcase_driver.c @@ -23,141 +23,147 @@ #include <stdarg.h> #include <setjmp.h> #include <string.h> +#include <limits.h> #ifdef __WIN32__ -#undef HAVE_VSNPRINTF -#define HAVE_VSNPRINTF 1 -#define vsnprintf _vsnprintf +static void my_vsnprintf(char *outBuf, size_t size, const char *format, va_list ap) +{ + _vsnprintf(outBuf, size, format, ap); + outBuf[size-1] = 0; /* be sure string is terminated */ +} +#elif defined(HAVE_VSNPRINTF) +# define my_vsnprintf(B,S,F,A) (void)vsnprintf(B,S,F,A) +#else +# warning Using unsafe 'vsprintf' without buffer overflow protection +# define my_vsnprintf(B,S,F,A) (void)vsprintf(B,F,A) #endif -#ifndef HAVE_VSNPRINTF -#define HAVE_VSNPRINTF 0 -#endif +static void my_snprintf(char *outBuf, size_t size, const char *format, ...) +{ + va_list ap; + va_start(ap, format); + my_vsnprintf(outBuf, size, format, ap); + va_end(ap); +} #define COMMENT_BUF_SZ 4096 #define TESTCASE_FAILED 0 #define TESTCASE_SKIPPED 1 #define TESTCASE_SUCCEEDED 2 +#define TESTCASE_CONTINUE 3 typedef struct { TestCaseState_t visible; - ErlDrvPort port; - ErlDrvTermData port_id; int result; - jmp_buf done_jmp_buf; + jmp_buf* done_jmp_buf; char *comment; char comment_buf[COMMENT_BUF_SZ]; } InternalTestCaseState_t; -ErlDrvData testcase_drv_start(ErlDrvPort port, char *command); -void testcase_drv_stop(ErlDrvData drv_data); -void testcase_drv_run(ErlDrvData drv_data, char *buf, ErlDrvSizeT len); - -static ErlDrvEntry testcase_drv_entry = { - NULL, - testcase_drv_start, - testcase_drv_stop, - testcase_drv_run, - NULL, - NULL, - "testcase_drv", - NULL, - NULL, - NULL, - NULL, - NULL, - NULL, - NULL, - NULL, - NULL, - ERL_DRV_EXTENDED_MARKER, - ERL_DRV_EXTENDED_MAJOR_VERSION, - ERL_DRV_EXTENDED_MINOR_VERSION, - 0, - NULL, - NULL, - NULL +ERL_NIF_TERM testcase_nif_start(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]); +ERL_NIF_TERM testcase_nif_stop(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]); +ERL_NIF_TERM testcase_nif_run(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]); + +ErlNifFunc testcase_nif_funcs[] = +{ + {"start", 1, testcase_nif_start}, + {"run", 1, testcase_nif_run}, + {"stop", 1, testcase_nif_stop} }; +static ErlNifResourceType* testcase_rt; +static ERL_NIF_TERM print_atom; -DRIVER_INIT(testcase_drv) +int testcase_nif_init(ErlNifEnv* env, void** priv_data, ERL_NIF_TERM load_info) { - testcase_drv_entry.driver_name = testcase_name(); - return &testcase_drv_entry; + testcase_rt = enif_open_resource_type(env, NULL, "testcase_rt", NULL, + ERL_NIF_RT_CREATE, NULL); + + print_atom = enif_make_atom(env, "print"); + return 0; } -ErlDrvData -testcase_drv_start(ErlDrvPort port, char *command) -{ +ERL_NIF_TERM +testcase_nif_start(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]) +{ /* (ThrNr, FreeMeg, BuildType) */ + ERL_NIF_TERM ret; InternalTestCaseState_t *itcs = (InternalTestCaseState_t *) - driver_alloc(sizeof(InternalTestCaseState_t)); - if (!itcs) { - return ERL_DRV_ERROR_GENERAL; + enif_alloc_resource(testcase_rt, sizeof(InternalTestCaseState_t)); + int free_megabyte; + const int max_megabyte = INT_MAX / (1024*1024); + const ERL_NIF_TERM* tpl; + int tpl_arity; + + if (!itcs + || !enif_get_tuple(env, argv[0], &tpl_arity, &tpl) + || tpl_arity != 3 + || !enif_get_int(env, tpl[0], &itcs->visible.thr_nr) + || !enif_get_int(env, tpl[1], &free_megabyte)) { + enif_make_badarg(env); } - + itcs->visible.free_mem = (free_megabyte < max_megabyte ? + free_megabyte : max_megabyte) * (1024*1024); itcs->visible.testcase_name = testcase_name(); + itcs->visible.build_type = tpl[2]; itcs->visible.extra = NULL; - itcs->port = port; - itcs->port_id = driver_mk_port(port); itcs->result = TESTCASE_FAILED; itcs->comment = ""; - return (ErlDrvData) itcs; + ret = enif_make_resource(env, itcs); + enif_release_resource(itcs); + return ret; } -void -testcase_drv_stop(ErlDrvData drv_data) +ERL_NIF_TERM +testcase_nif_stop(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]) { - testcase_cleanup((TestCaseState_t *) drv_data); - driver_free((void *) drv_data); + InternalTestCaseState_t *itcs; + if (!enif_get_resource(env, argv[0], testcase_rt, (void**)&itcs)) + return enif_make_badarg(env); + testcase_cleanup(&itcs->visible); + return enif_make_atom(env,"ok"); } -void -testcase_drv_run(ErlDrvData drv_data, char *buf, ErlDrvSizeT len) +ERL_NIF_TERM +testcase_nif_run(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]) { - InternalTestCaseState_t *itcs = (InternalTestCaseState_t *) drv_data; - ErlDrvTermData result_atom; - ErlDrvTermData msg[12]; + InternalTestCaseState_t *itcs; + const char* result_atom; + jmp_buf the_jmp_buf; + + if (!enif_get_resource(env, argv[0], testcase_rt, (void**)&itcs)) + return enif_make_badarg(env); - itcs->visible.command = buf; - itcs->visible.command_len = len; + itcs->visible.curr_env = env; - if (setjmp(itcs->done_jmp_buf) == 0) { - testcase_run((TestCaseState_t *) itcs); + /* For some unknown reason, first call to setjmp crashes on win64 + * when jmp_buf is allocated as part of the resource. But it works when + * allocated on stack. It used to work when this was a driver. + */ + itcs->done_jmp_buf = &the_jmp_buf; + + if (setjmp(the_jmp_buf) == 0) { + testcase_run(&itcs->visible); itcs->result = TESTCASE_SUCCEEDED; } switch (itcs->result) { - case TESTCASE_SUCCEEDED: - result_atom = driver_mk_atom("succeeded"); - break; - case TESTCASE_SKIPPED: - result_atom = driver_mk_atom("skipped"); - break; - case TESTCASE_FAILED: + case TESTCASE_CONTINUE: + return enif_make_atom(env, "continue"); + + case TESTCASE_SUCCEEDED: result_atom = "succeeded"; break; + case TESTCASE_SKIPPED: result_atom = "skipped"; break; + case TESTCASE_FAILED: result_atom = "failed"; break; default: - result_atom = driver_mk_atom("failed"); - break; + result_atom = "failed"; + my_snprintf(itcs->comment_buf, sizeof(itcs->comment_buf), + "Unexpected test result code %d.", itcs->result); + itcs->comment = itcs->comment_buf; } - msg[0] = ERL_DRV_ATOM; - msg[1] = (ErlDrvTermData) result_atom; - - msg[2] = ERL_DRV_PORT; - msg[3] = itcs->port_id; - - msg[4] = ERL_DRV_ATOM; - msg[5] = driver_mk_atom(itcs->visible.testcase_name); - - msg[6] = ERL_DRV_STRING; - msg[7] = (ErlDrvTermData) itcs->comment; - msg[8] = (ErlDrvTermData) strlen(itcs->comment); - - msg[9] = ERL_DRV_TUPLE; - msg[10] = (ErlDrvTermData) 4; - - erl_drv_output_term(itcs->port_id, msg, 11); + return enif_make_tuple2(env, enif_make_atom(env, result_atom), + enif_make_string(env, itcs->comment, ERL_NIF_LATIN1)); } int @@ -172,34 +178,22 @@ testcase_assertion_failed(TestCaseState_t *tcs, void testcase_printf(TestCaseState_t *tcs, char *frmt, ...) { - InternalTestCaseState_t *itcs = (InternalTestCaseState_t *) tcs; - ErlDrvTermData msg[12]; + InternalTestCaseState_t* itcs = (InternalTestCaseState_t*)tcs; + ErlNifPid pid; + ErlNifEnv* msg_env = enif_alloc_env(); + ERL_NIF_TERM msg; va_list va; va_start(va, frmt); -#if HAVE_VSNPRINTF - vsnprintf(itcs->comment_buf, COMMENT_BUF_SZ, frmt, va); -#else - vsprintf(itcs->comment_buf, frmt, va); -#endif + my_vsnprintf(itcs->comment_buf, COMMENT_BUF_SZ, frmt, va); va_end(va); - msg[0] = ERL_DRV_ATOM; - msg[1] = (ErlDrvTermData) driver_mk_atom("print"); + msg = enif_make_tuple2(msg_env, print_atom, + enif_make_string(msg_env, itcs->comment_buf, ERL_NIF_LATIN1)); - msg[2] = ERL_DRV_PORT; - msg[3] = itcs->port_id; + enif_send(itcs->visible.curr_env, enif_self(itcs->visible.curr_env, &pid), + msg_env, msg); - msg[4] = ERL_DRV_ATOM; - msg[5] = driver_mk_atom(itcs->visible.testcase_name); - - msg[6] = ERL_DRV_STRING; - msg[7] = (ErlDrvTermData) itcs->comment_buf; - msg[8] = (ErlDrvTermData) strlen(itcs->comment_buf); - - msg[9] = ERL_DRV_TUPLE; - msg[10] = (ErlDrvTermData) 4; - - erl_drv_output_term(itcs->port_id, msg, 11); + enif_free_env(msg_env); } @@ -208,17 +202,13 @@ void testcase_succeeded(TestCaseState_t *tcs, char *frmt, ...) InternalTestCaseState_t *itcs = (InternalTestCaseState_t *) tcs; va_list va; va_start(va, frmt); -#if HAVE_VSNPRINTF - vsnprintf(itcs->comment_buf, COMMENT_BUF_SZ, frmt, va); -#else - vsprintf(itcs->comment_buf, frmt, va); -#endif + my_vsnprintf(itcs->comment_buf, COMMENT_BUF_SZ, frmt, va); va_end(va); itcs->result = TESTCASE_SUCCEEDED; itcs->comment = itcs->comment_buf; - longjmp(itcs->done_jmp_buf, 1); + longjmp(*itcs->done_jmp_buf, 1); } void testcase_skipped(TestCaseState_t *tcs, char *frmt, ...) @@ -226,17 +216,20 @@ void testcase_skipped(TestCaseState_t *tcs, char *frmt, ...) InternalTestCaseState_t *itcs = (InternalTestCaseState_t *) tcs; va_list va; va_start(va, frmt); -#if HAVE_VSNPRINTF - vsnprintf(itcs->comment_buf, COMMENT_BUF_SZ, frmt, va); -#else - vsprintf(itcs->comment_buf, frmt, va); -#endif + my_vsnprintf(itcs->comment_buf, COMMENT_BUF_SZ, frmt, va); va_end(va); itcs->result = TESTCASE_SKIPPED; itcs->comment = itcs->comment_buf; - longjmp(itcs->done_jmp_buf, 1); + longjmp(*itcs->done_jmp_buf, 1); +} + +void testcase_continue(TestCaseState_t *tcs) +{ + InternalTestCaseState_t *itcs = (InternalTestCaseState_t *) tcs; + itcs->result = TESTCASE_CONTINUE; + longjmp(*itcs->done_jmp_buf, 1); } void testcase_failed(TestCaseState_t *tcs, char *frmt, ...) @@ -246,37 +239,33 @@ void testcase_failed(TestCaseState_t *tcs, char *frmt, ...) size_t bufsz = sizeof(buf); va_list va; va_start(va, frmt); -#if HAVE_VSNPRINTF - vsnprintf(itcs->comment_buf, COMMENT_BUF_SZ, frmt, va); -#else - vsprintf(itcs->comment_buf, frmt, va); -#endif + my_vsnprintf(itcs->comment_buf, COMMENT_BUF_SZ, frmt, va); va_end(va); itcs->result = TESTCASE_FAILED; itcs->comment = itcs->comment_buf; - if (erl_drv_getenv("ERL_ABORT_ON_FAILURE", buf, &bufsz) == 0 + if (enif_getenv("ERL_ABORT_ON_FAILURE", buf, &bufsz) == 0 && strcmp("true", buf) == 0) { fprintf(stderr, "Testcase \"%s\" failed: %s\n", itcs->visible.testcase_name, itcs->comment); abort(); } - longjmp(itcs->done_jmp_buf, 1); + longjmp(*itcs->done_jmp_buf, 1); } void *testcase_alloc(size_t size) { - return driver_alloc(size); + return enif_alloc(size); } void *testcase_realloc(void *ptr, size_t size) { - return driver_realloc(ptr, size); + return enif_realloc(ptr, size); } void testcase_free(void *ptr) { - driver_free(ptr); + enif_free(ptr); } diff --git a/erts/emulator/test/alloc_SUITE_data/testcase_driver.h b/erts/emulator/test/alloc_SUITE_data/testcase_driver.h index 5d17eaec64..f0ca91bd06 100644 --- a/erts/emulator/test/alloc_SUITE_data/testcase_driver.h +++ b/erts/emulator/test/alloc_SUITE_data/testcase_driver.h @@ -20,13 +20,15 @@ #ifndef TESTCASE_DRIVER_H__ #define TESTCASE_DRIVER_H__ -#include "erl_driver.h" +#include "erl_nif.h" #include <stdlib.h> typedef struct { + ErlNifEnv* curr_env; char *testcase_name; - char *command; - int command_len; + int thr_nr; + int free_mem; /* in bytes */ + ERL_NIF_TERM build_type; /* opt, debug, valgrind, ... */ void *extra; } TestCaseState_t; @@ -34,9 +36,11 @@ typedef struct { ((void) ((B) ? 1 : testcase_assertion_failed((TCS), __FILE__, __LINE__, #B))) +int testcase_nif_init(ErlNifEnv* env, void** priv_data, ERL_NIF_TERM load_info); void testcase_printf(TestCaseState_t *tcs, char *frmt, ...); void testcase_succeeded(TestCaseState_t *tcs, char *frmt, ...); void testcase_skipped(TestCaseState_t *tcs, char *frmt, ...); +void testcase_continue(TestCaseState_t *tcs); void testcase_failed(TestCaseState_t *tcs, char *frmt, ...); int testcase_assertion_failed(TestCaseState_t *tcs, char *file, int line, char *assertion); @@ -45,8 +49,11 @@ void *testcase_realloc(void *ptr, size_t size); void testcase_free(void *ptr); +/* Implemented by testcase: */ char *testcase_name(void); void testcase_run(TestCaseState_t *tcs); void testcase_cleanup(TestCaseState_t *tcs); -#endif +extern ErlNifFunc testcase_nif_funcs[3]; + +#endif /* TESTCASE_DRIVER_H__ */ diff --git a/erts/emulator/test/alloc_SUITE_data/threads.c b/erts/emulator/test/alloc_SUITE_data/threads.c index edad24ee6b..a8a6a23695 100644 --- a/erts/emulator/test/alloc_SUITE_data/threads.c +++ b/erts/emulator/test/alloc_SUITE_data/threads.c @@ -86,7 +86,7 @@ static void fail(int t_no, char *frmt, ...) tc_failed = 1; - if (erl_drv_getenv("ERL_ABORT_ON_FAILURE", buf, &bufsz) == 0 + if (enif_getenv("ERL_ABORT_ON_FAILURE", buf, &bufsz) == 0 && strcmp("true", buf) == 0) { fprintf(stderr, "Testcase \"%s\" failed: %s\n", testcase_name(), err_buf); @@ -187,7 +187,6 @@ testcase_run(TestCaseState_t *tcs) for(i = 1; i <= NO_OF_THREADS; i++) { char *alc; - int res; threads[i].arg.no_ops_per_bl = NO_OF_OPS_PER_BL; @@ -446,3 +445,6 @@ thread_func(void *arg) exit_thread(td->t_no, 1); return NULL; } + +ERL_NIF_INIT(threads, testcase_nif_funcs, testcase_nif_init, + NULL, NULL, NULL); diff --git a/erts/emulator/test/alloc_SUITE_data/threads.erl b/erts/emulator/test/alloc_SUITE_data/threads.erl new file mode 100644 index 0000000000..a7b4965f5e --- /dev/null +++ b/erts/emulator/test/alloc_SUITE_data/threads.erl @@ -0,0 +1,10 @@ +-module(threads). + +-export([init/1, start/1, run/1, stop/1]). + +init(File) -> + ok = erlang:load_nif(File, 0). + +start(_) -> erlang:nif_error(not_loaded). +run(_) -> erlang:nif_error(not_loaded). +stop(_) -> erlang:nif_error(not_loaded). diff --git a/erts/emulator/test/distribution_SUITE_data/run.erl b/erts/emulator/test/distribution_SUITE_data/run.erl index f5169e160c..d5ed139369 100644 --- a/erts/emulator/test/distribution_SUITE_data/run.erl +++ b/erts/emulator/test/distribution_SUITE_data/run.erl @@ -30,16 +30,19 @@ from(H, [_ | T]) -> from(H, T); from(H, []) -> []. start() -> - net_kernel:start([fideridum,shortnames]), - {ok, Node} = slave:start(host(), heppel), - P = spawn(Node, a, b, []), - B1 = term_to_binary(P), - N1 = node(P), - ok = net_kernel:stop(), - N2 = node(P), - io:format("~w~n", [N1 == N2]), + Result = do_it(), + + %% Do GCs and node_and_dist_references + %% in an attempt to crash the VM (without OTP-13076 fix) + lists:foreach(fun(P) -> erlang:garbage_collect(P) end, + processes()), + erts_debug:set_internal_state(available_internal_state, true), + erts_debug:get_internal_state(node_and_dist_references), + + io:format("~w~n", [Result]), + if - N1 == N2 -> + Result -> init:stop(); true -> %% Make sure that the io:format/2 output is really written @@ -47,3 +50,29 @@ start() -> erlang:yield(), init:stop() end. + + +do_it() -> + {ok, _} = net_kernel:start([fideridum,shortnames]), + {ok, Node} = slave:start(host(), heppel), + P = spawn(Node, net_kernel, stop, []), + B1 = term_to_binary(P), + N1 = node(P), + ok = net_kernel:stop(), + N2 = node(P), + + %% OTP-13076 + %% Restart distribution with same node name as previous remote node + %% Repeat to wrap around creation + Result = lists:foldl(fun(_, Acc) -> + timer:sleep(2), % give net_kernel:stop() time to take effect :-( + {ok, _} = net_kernel:start([heppel,shortnames]), + N3 = node(P), + ok = net_kernel:stop(), + N4 = node(P), + Acc and (N3 =:= N1) and (N4 =:= N1) + end, + (N2 =:= N1), + lists:seq(1,3)), + + Result. diff --git a/erts/emulator/test/map_SUITE.erl b/erts/emulator/test/map_SUITE.erl index 886ae7d516..6890c42b7a 100644 --- a/erts/emulator/test/map_SUITE.erl +++ b/erts/emulator/test/map_SUITE.erl @@ -58,6 +58,7 @@ %% erlang t_erlang_hash/1, t_map_encode_decode/1, + t_gc_rare_map_overflow/1, %% non specific BIF related t_bif_build_and_check/1, @@ -121,6 +122,7 @@ all() -> [ %% erlang t_erlang_hash, t_map_encode_decode, + t_gc_rare_map_overflow, t_map_size, t_is_map, %% non specific BIF related @@ -2181,7 +2183,9 @@ t_map_encode_decode(Config) when is_list(Config) -> {<<>>, sc9}, {3.14158, sc10}, {[3.14158], sc11}, {more_atoms, sc12}, {{more_tuples}, sc13}, {self(), sc14}, - {{},{}},{[],[]} + {{},{}},{[],[]}, + {map_s, #{a=>a, 2=>b, 3=>c}}, + {map_l, maps:from_list([{I,I}||I <- lists:seq(1,74)])} ], ok = map_encode_decode_and_match(Pairs,[],#{}), @@ -2245,9 +2249,30 @@ t_map_encode_decode(Config) when is_list(Config) -> %% bad size (too small) .. should fail just truncate it .. weird. %% possibly change external format so truncated will be #{a:=1} - #{ a:=b } = - erlang:binary_to_term(<<131,116,0,0,0,1,100,0,1,97,100,0,1,98,97,1,97,1>>), - + #{ a:=b } = erlang:binary_to_term(<<131,116,0,0,0,1,100,0,1,97,100,0,1,98,97,1,97,1>>), + + %% specific fannerl (opensource app) binary_to_term error in 18.1 + + #{bias := {1,1,0}, + bit_fail := 0, + connections := #{{2,9} := _, + {8,14} := _, + {2,12} := _, + {5,7} := _, + {11,16} := _, + {11,15} := _}, + layers := {5,7,3}, + network_type := fann_nettype_layer, + num_input := 5, + num_layers := 3, + num_output := 3, + rprop_delta_max := _, + rprop_delta_min := _, + total_connections := 66, + total_neurons := 17, + train_error_function := fann_errorfunc_tanh, + train_stop_function := fann_stopfunc_mse, + training_algorithm := fann_train_rprop} = erlang:binary_to_term(fannerl()), ok. map_encode_decode_and_match([{K,V}|Pairs], EncodedPairs, M0) -> @@ -2966,3 +2991,176 @@ do_badmap_17(Config) -> %% Use this function to avoid compile-time evaluation of an expression. id(I) -> I. + + +%% OTP-13146 +%% Provoke major GC with a lot of "fat" maps on external format in msg queue +%% causing heap fragments to be allocated. +t_gc_rare_map_overflow(Config) -> + Pa = filename:dirname(code:which(?MODULE)), + {ok, Node} = test_server:start_node(gc_rare_map_overflow, slave, [{args, "-pa \""++Pa++"\""}]), + Echo = spawn_link(Node, fun Loop() -> receive {From,Msg} -> From ! Msg + end, + Loop() + end), + FatMap = fatmap(34), + false = (flatmap =:= erts_internal:map_type(FatMap)), + + t_gc_rare_map_overflow_do(Echo, FatMap, fun() -> erlang:garbage_collect() end), + + % Repeat test for minor gc: + minor_collect(), % need this to make the next gc really be a minor + t_gc_rare_map_overflow_do(Echo, FatMap, fun() -> true = minor_collect() end), + + unlink(Echo), + test_server:stop_node(Node). + +t_gc_rare_map_overflow_do(Echo, FatMap, GcFun) -> + Master = self(), + true = receive M -> false after 0 -> true end, % assert empty msg queue + Echo ! {Master, token}, + repeat(1000, fun(_) -> Echo ! {Master, FatMap} end, void), + + timer:sleep(100), % Wait for maps to arrive in our msg queue + token = receive Tok -> Tok end, % and provoke move from outer to inner msg queue + + %% Do GC that will "overflow" and create heap frags due to all the fat maps + GcFun(), + + %% Now check that all maps in msg queueu are intact + %% Will crash emulator in OTP-18.1 + repeat(1000, fun(_) -> FatMap = receive FM -> FM end end, void), + ok. + +minor_collect() -> + minor_collect(minor_gcs()). + +minor_collect(Before) -> + After = minor_gcs(), + case After of + _ when After > Before -> true; + _ when After =:= Before -> minor_collect(Before); + 0 -> false + end. + +minor_gcs() -> + {garbage_collection, Info} = process_info(self(), garbage_collection), + {minor_gcs, GCS} = lists:keyfind(minor_gcs, 1, Info), + GCS. + +%% Generate a map with N (or N+1) keys that has an abnormal heap demand. +%% Done by finding keys that collide in the first 32-bit hash. +fatmap(N) -> + erts_debug:set_internal_state(available_internal_state, true), + Table = ets:new(void, [bag, private]), + + Seed0 = rand:seed_s(exsplus, {4711, 3141592, 2718281}), + Seed1 = fatmap_populate(Table, Seed0, (1 bsl 16)), + Keys = fatmap_generate(Table, Seed1, N, []), + ets:delete(Table), + maps:from_list([{K,K} || K <- Keys]). + +fatmap_populate(_, Seed, 0) -> Seed; +fatmap_populate(Table, Seed, N) -> + {I, NextSeed} = rand:uniform_s(1 bsl 48, Seed), + Hash = internal_hash(I), + ets:insert(Table, [{Hash, I}]), + fatmap_populate(Table, NextSeed, N-1). + + +fatmap_generate(_, _, N, Acc) when N =< 0 -> + Acc; +fatmap_generate(Table, Seed, N0, Acc0) -> + {I, NextSeed} = rand:uniform_s(1 bsl 48, Seed), + Hash = internal_hash(I), + case ets:member(Table, Hash) of + true -> + NewKeys = [I | ets:lookup_element(Table, Hash, 2)], + Acc1 = lists:usort(Acc0 ++ NewKeys), + N1 = N0 - (length(Acc1) - length(Acc0)), + fatmap_generate(Table, NextSeed, N1, Acc1); + false -> + fatmap_generate(Table, NextSeed, N0, Acc0) + end. + +internal_hash(Term) -> + erts_debug:get_internal_state({internal_hash, Term}). + + +%% map external_format (fannerl). +fannerl() -> + <<131,116,0,0,0,28,100,0,13,108,101,97,114,110,105,110,103,95,114, + 97,116,101,70,63,230,102,102,96,0,0,0,100,0,17,108,101,97,114,110,105,110, + 103,95,109,111,109,101,110,116,117,109,70,0,0,0,0,0,0,0,0,100,0, + 18,116,114,97,105,110,105,110,103,95,97,108,103,111,114,105,116,104,109,100,0, + 16,102,97,110,110,95,116,114,97,105,110,95,114,112,114,111,112, + 100,0,17,109,101,97,110,95,115,113,117,97,114,101,95,101,114,114,111,114,70, + 0,0,0,0,0,0,0,0,100,0,8,98,105,116,95,102,97,105,108,97,0,100,0,20, + 116,114,97,105,110,95,101,114,114,111,114,95,102,117,110,99,116,105,111, + 110,100,0,19,102,97,110,110,95,101,114,114,111,114,102,117,110,99, + 95,116,97,110,104,100,0,9,110,117,109,95,105,110,112,117,116,97,5,100,0,10,110, + 117,109,95,111,117,116,112,117,116,97,3,100,0,13,116,111,116,97,108, + 95,110,101,117,114,111,110,115,97,17,100,0,17,116,111,116,97,108,95,99,111,110, + 110,101,99,116,105,111,110,115,97,66,100,0,12,110,101,116,119,111,114,107, + 95,116,121,112,101,100,0,18,102,97,110,110,95,110,101,116,116,121,112,101, + 95,108,97,121,101,114,100,0,15,99,111,110,110,101,99,116,105,111,110,95, + 114,97,116,101,70,63,240,0,0,0,0,0,0,100,0,10,110,117,109,95,108,97,121,101, + 114,115,97,3,100,0,19,116,114,97,105,110,95,115,116,111,112,95,102,117,110, + 99,116,105,111,110,100,0,17,102,97,110,110,95,115,116,111,112,102,117,110, + 99,95,109,115,101,100,0,15,113,117,105,99,107,112,114,111,112,95,100,101,99, + 97,121,70,191,26,54,226,224,0,0,0,100,0,12,113,117,105,99,107,112,114, + 111,112,95,109,117,70,63,252,0,0,0,0,0,0,100,0,21,114,112,114,111,112,95,105, + 110,99,114,101,97,115,101,95,102,97,99,116,111,114,70,63,243,51,51, + 64,0,0,0,100,0,21,114,112,114,111,112,95,100,101,99,114,101,97,115,101, + 95,102,97,99,116,111,114,70,63,224,0,0,0,0,0,0,100,0,15,114,112,114,111,112, + 95,100,101,108,116,97,95,109,105,110,70,0,0,0,0,0,0,0,0,100,0,15,114,112,114, + 111,112,95,100,101,108,116,97,95,109,97,120,70,64,73,0,0,0,0,0,0,100,0, + 16,114,112,114,111,112,95,100,101,108,116,97,95,122,101,114,111,70,63,185,153, + 153,160,0,0,0,100,0,26,115,97,114,112,114,111,112,95,119,101,105,103, + 104,116,95,100,101,99,97,121,95,115,104,105,102,116,70,192,26,147,116,192,0,0,0, + 100,0,35,115,97,114,112,114,111,112,95,115,116,101,112,95,101,114, + 114,111,114,95,116,104,114,101,115,104,111,108,100,95,102,97,99,116,111,114,70, + 63,185,153,153,160,0,0,0,100,0,24,115,97,114,112,114,111,112,95,115, + 116,101,112,95,101,114,114,111,114,95,115,104,105,102,116,70,63,246,40,245, + 192,0,0,0,100,0,19,115,97,114,112,114,111,112,95,116,101,109,112,101,114, + 97,116,117,114,101,70,63,142,184,81,224,0,0,0,100,0,6,108,97,121,101,114,115, + 104,3,97,5,97,7,97,3,100,0,4,98,105,97,115,104,3,97,1,97,1,97,0,100,0,11, + 99,111,110,110,101,99,116,105,111,110,115,116,0,0,0,66,104,2,97,0,97,6,70, + 191,179,51,44,64,0,0,0,104,2,97,1,97,6,70,63,178,130,90,32,0,0,0,104,2,97,2, + 97,6,70,63,82,90,88,0,0,0,0,104,2,97,3,97,6,70,63,162,91,63,192,0,0,0,104,2, + 97,4,97,6,70,191,151,70,169,0,0,0,0,104,2,97,5,97,6,70,191,117,52,222,0,0,0, + 0,104,2,97,0,97,7,70,63,152,240,139,0,0,0,0,104,2,97,1,97,7,70,191,166,31, + 187,160,0,0,0,104,2,97,2,97,7,70,191,150,70,63,0,0,0,0,104,2,97,3,97,7,70, + 63,152,181,126,128,0,0,0,104,2,97,4,97,7,70,63,151,187,162,128,0,0,0,104,2, + 97,5,97,7,70,191,143,161,101,0,0,0,0,104,2,97,0,97,8,70,191,153,102,36,128,0, + 0,0,104,2,97,1,97,8,70,63,160,139,250,64,0,0,0,104,2,97,2,97,8,70,63,164,62, + 196,64,0,0,0,104,2,97,3,97,8,70,191,178,78,209,192,0,0,0,104,2,97,4,97,8,70, + 191,185,19,76,224,0,0,0,104,2,97,5,97,8,70,63,183,142,196,96,0,0,0,104,2,97,0, + 97,9,70,63,150,104,248,0,0,0,0,104,2,97,1,97,9,70,191,164,4,100,224,0,0,0, + 104,2,97,2,97,9,70,191,169,42,42,224,0,0,0,104,2,97,3,97,9,70,63,145,54,78,128,0, + 0,0,104,2,97,4,97,9,70,63,126,243,134,0,0,0,0,104,2,97,5,97,9,70,63,177, + 203,25,96,0,0,0,104,2,97,0,97,10,70,63,172,104,47,64,0,0,0,104,2,97,1,97,10, + 70,63,161,242,193,64,0,0,0,104,2,97,2,97,10,70,63,175,208,241,192,0,0,0,104,2, + 97,3,97,10,70,191,129,202,161,0,0,0,0,104,2,97,4,97,10,70,63,178,151,55,32,0,0,0, + 104,2,97,5,97,10,70,63,137,155,94,0,0,0,0,104,2,97,0,97,11,70,191,179, + 106,160,0,0,0,0,104,2,97,1,97,11,70,63,184,253,164,96,0,0,0,104,2,97,2,97,11, + 70,191,143,30,157,0,0,0,0,104,2,97,3,97,11,70,63,153,225,140,128,0,0,0,104, + 2,97,4,97,11,70,63,161,35,85,192,0,0,0,104,2,97,5,97,11,70,63,175,200,55,192, + 0,0,0,104,2,97,0,97,12,70,191,180,116,132,96,0,0,0,104,2,97,1,97,12,70,191, + 165,151,152,0,0,0,0,104,2,97,2,97,12,70,191,180,197,91,160,0,0,0,104,2,97,3,97,12, + 70,191,91,30,160,0,0,0,0,104,2,97,4,97,12,70,63,180,251,45,32,0,0,0, + 104,2,97,5,97,12,70,63,165,134,77,64,0,0,0,104,2,97,6,97,14,70,63,181,56,242,96, + 0,0,0,104,2,97,7,97,14,70,191,165,239,234,224,0,0,0,104,2,97,8,97,14, + 70,191,154,65,216,128,0,0,0,104,2,97,9,97,14,70,63,150,250,236,0,0,0,0,104,2,97, + 10,97,14,70,191,141,105,108,0,0,0,0,104,2,97,11,97,14,70,191,152,40, + 165,0,0,0,0,104,2,97,12,97,14,70,63,141,159,46,0,0,0,0,104,2,97,13,97,14,70, + 191,183,172,137,32,0,0,0,104,2,97,6,97,15,70,63,163,26,123,192,0,0,0,104, + 2,97,7,97,15,70,63,176,184,106,32,0,0,0,104,2,97,8,97,15,70,63,152,234,144, + 0,0,0,0,104,2,97,9,97,15,70,191,172,58,70,160,0,0,0,104,2,97,10,97,15,70, + 63,161,211,211,192,0,0,0,104,2,97,11,97,15,70,191,148,171,120,128,0,0,0,104, + 2,97,12,97,15,70,63,180,117,214,224,0,0,0,104,2,97,13,97,15,70,191,104, + 230,216,0,0,0,0,104,2,97,6,97,16,70,63,178,53,103,96,0,0,0,104,2,97,7,97,16, + 70,63,170,230,232,64,0,0,0,104,2,97,8,97,16,70,191,183,45,100,192,0,0,0, + 104,2,97,9,97,16,70,63,184,100,97,32,0,0,0,104,2,97,10,97,16,70,63,169,174, + 254,64,0,0,0,104,2,97,11,97,16,70,191,119,121,234,0,0,0,0,104,2,97,12,97, + 16,70,63,149,12,170,128,0,0,0,104,2,97,13,97,16,70,191,144,193,191,0,0,0,0>>. diff --git a/erts/emulator/test/nif_SUITE_data/nif_mod.c b/erts/emulator/test/nif_SUITE_data/nif_mod.c index 9c78c0e04d..f7e729e2b6 100644 --- a/erts/emulator/test/nif_SUITE_data/nif_mod.c +++ b/erts/emulator/test/nif_SUITE_data/nif_mod.c @@ -240,7 +240,7 @@ static ERL_NIF_TERM lib_version(ErlNifEnv* env, int argc, const ERL_NIF_TERM arg static ERL_NIF_TERM get_priv_data_ptr(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]) { ADD_CALL("get_priv_data_ptr"); - return enif_make_ulong(env, (unsigned long)priv_data(env)); + return enif_make_uint64(env, (ErlNifUInt64)priv_data(env)); } static ERL_NIF_TERM make_new_resource(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]) diff --git a/erts/etc/common/ct_run.c b/erts/etc/common/ct_run.c index 548514ee6c..11cec26264 100644 --- a/erts/etc/common/ct_run.c +++ b/erts/etc/common/ct_run.c @@ -83,7 +83,6 @@ static int eargc; /* Number of arguments in eargv. */ static void error(char* format, ...); static char* emalloc(size_t size); static char* strsave(char* string); -static void push_words(char* src); static int run_erlang(char* name, char** argv); static char* get_default_emulator(char* progname); #ifdef __WIN32__ @@ -152,6 +151,8 @@ int main(int argc, char** argv) argv0 = argv; emulator = get_default_emulator(argv[0]); + if (strlen(emulator) >= MAXPATHLEN) + error("Emulator path length is too large"); /* * Allocate the argv vector to be used for arguments to Erlang. @@ -163,7 +164,7 @@ int main(int argc, char** argv) eargv_base = (char **) emalloc(eargv_size*sizeof(char*)); eargv = eargv_base; eargc = 0; - push_words(emulator); + PUSH(strsave(emulator)); eargc_base = eargc; eargv = eargv + eargv_size/2; eargc = 0; @@ -294,26 +295,6 @@ int main(int argc, char** argv) return run_erlang(eargv[0], eargv); } -static void -push_words(char* src) -{ - char sbuf[MAXPATHLEN]; - char* dst; - - dst = sbuf; - while ((*dst++ = *src++) != '\0') { - if (isspace((int)*src)) { - *dst = '\0'; - PUSH(strsave(sbuf)); - dst = sbuf; - do { - src++; - } while (isspace((int)*src)); - } - } - if (sbuf[0]) - PUSH(strsave(sbuf)); -} #ifdef __WIN32__ wchar_t *make_commandline(char **argv) { diff --git a/erts/etc/common/dialyzer.c b/erts/etc/common/dialyzer.c index c45626606c..cac1464bf6 100644 --- a/erts/etc/common/dialyzer.c +++ b/erts/etc/common/dialyzer.c @@ -65,7 +65,6 @@ static int eargc; /* Number of arguments in eargv. */ static void error(char* format, ...); static char* emalloc(size_t size); static char* strsave(char* string); -static void push_words(char* src); static int run_erlang(char* name, char** argv); static char* get_default_emulator(char* progname); #ifdef __WIN32__ @@ -189,7 +188,7 @@ int main(int argc, char** argv) eargv_base = (char **) emalloc(eargv_size*sizeof(char*)); eargv = eargv_base; eargc = 0; - push_words(emulator); + PUSH(strsave(emulator)); eargc_base = eargc; eargv = eargv + eargv_size/2; eargc = 0; @@ -269,27 +268,6 @@ int main(int argc, char** argv) return run_erlang(eargv[0], eargv); } -static void -push_words(char* src) -{ - char sbuf[MAXPATHLEN]; - char* dst; - - dst = sbuf; - while ((*dst++ = *src++) != '\0') { - if (isspace((int)*src)) { - *dst = '\0'; - PUSH(strsave(sbuf)); - dst = sbuf; - do { - src++; - } while (isspace((int)*src)); - } - } - if (sbuf[0]) - PUSH(strsave(sbuf)); -} - #ifdef __WIN32__ wchar_t *make_commandline(char **argv) { diff --git a/erts/etc/common/erlc.c b/erts/etc/common/erlc.c index f9d909e01c..049afc526a 100644 --- a/erts/etc/common/erlc.c +++ b/erts/etc/common/erlc.c @@ -200,7 +200,7 @@ int main(int argc, char** argv) eargv_base = (char **) emalloc(eargv_size*sizeof(char*)); eargv = eargv_base; eargc = 0; - push_words(emulator); + PUSH(strsave(emulator)); eargc_base = eargc; eargv = eargv + eargv_size/2; eargc = 0; @@ -330,26 +330,6 @@ process_opt(int* pArgc, char*** pArgv, int offset) return argv[1]; } -static void -push_words(char* src) -{ - char sbuf[MAXPATHLEN]; - char* dst; - - dst = sbuf; - while ((*dst++ = *src++) != '\0') { - if (isspace((int)*src)) { - *dst = '\0'; - PUSH(strsave(sbuf)); - dst = sbuf; - do { - src++; - } while (isspace((int)*src)); - } - } - if (sbuf[0]) - PUSH(strsave(sbuf)); -} #ifdef __WIN32__ wchar_t *make_commandline(char **argv) { diff --git a/erts/etc/common/erlexec.c b/erts/etc/common/erlexec.c index 1e7c56dd8e..af1c198281 100644 --- a/erts/etc/common/erlexec.c +++ b/erts/etc/common/erlexec.c @@ -73,6 +73,7 @@ static const char plusM_au_allocs[]= { 'R', /* driver_alloc */ 'S', /* sl_alloc */ 'T', /* temp_alloc */ + 'Z', /* test_alloc */ '\0' }; diff --git a/erts/etc/common/escript.c b/erts/etc/common/escript.c index 7fd02ed436..a5c6d0d40b 100644 --- a/erts/etc/common/escript.c +++ b/erts/etc/common/escript.c @@ -74,7 +74,6 @@ static void error(char* format, ...); static char* emalloc(size_t size); static void efree(void *p); static char* strsave(char* string); -static void push_words(char* src); static int run_erlang(char* name, char** argv); static char* get_default_emulator(char* progname); #ifdef __WIN32__ @@ -432,7 +431,7 @@ main(int argc, char** argv) emulator = get_default_emulator(argv[0]); } - if (strlen(emulator) >= PMAX) + if (strlen(emulator) >= MAXPATHLEN) error("Value of environment variable ESCRIPT_EMULATOR is too large"); /* @@ -445,7 +444,7 @@ main(int argc, char** argv) eargv_base = (char **) emalloc(eargv_size*sizeof(char*)); eargv = eargv_base; eargc = 0; - push_words(emulator); + PUSH(strsave(emulator)); eargc_base = eargc; eargv = eargv + eargv_size/2; eargc = 0; @@ -554,26 +553,6 @@ main(int argc, char** argv) return run_erlang(eargv[0], eargv); } -static void -push_words(char* src) -{ - char sbuf[PMAX]; - char* dst; - - dst = sbuf; - while ((*dst++ = *src++) != '\0') { - if (isspace((int)*src)) { - *dst = '\0'; - PUSH(strsave(sbuf)); - dst = sbuf; - do { - src++; - } while (isspace((int)*src)); - } - } - if (sbuf[0]) - PUSH(strsave(sbuf)); -} #ifdef __WIN32__ wchar_t *make_commandline(char **argv) { diff --git a/erts/etc/common/heart.c b/erts/etc/common/heart.c index 01ef840b5d..9571b83ffd 100644 --- a/erts/etc/common/heart.c +++ b/erts/etc/common/heart.c @@ -718,14 +718,12 @@ do_terminate(int erlin_fd, int reason) { print_error("Would reboot. Terminating."); else { kill_old_erlang(); - /* suppress gcc warning with 'if' */ ret = system(command); print_error("Executed \"%s\" -> %d. Terminating.",command, ret); } free_env_val(command); } else { kill_old_erlang(); - /* suppress gcc warning with 'if' */ ret = system((char*)&cmd[0]); print_error("Executed \"%s\" -> %d. Terminating.",cmd, ret); } diff --git a/erts/etc/common/typer.c b/erts/etc/common/typer.c index 0aa0996808..7ff8aa76e2 100644 --- a/erts/etc/common/typer.c +++ b/erts/etc/common/typer.c @@ -65,7 +65,6 @@ static int eargc; /* Number of arguments in eargv. */ static void error(char* format, ...); static char* emalloc(size_t size); static char* strsave(char* string); -static void push_words(char* src); static int run_erlang(char* name, char** argv); static char* get_default_emulator(char* progname); #ifdef __WIN32__ @@ -129,6 +128,9 @@ main(int argc, char** argv) emulator = get_default_emulator(argv[0]); + if (strlen(emulator) >= MAXPATHLEN) + error("Emulator path length is too large"); + /* * Allocate the argv vector to be used for arguments to Erlang. * Arrange for starting to pushing information in the middle of @@ -139,7 +141,7 @@ main(int argc, char** argv) eargv_base = (char **) emalloc(eargv_size*sizeof(char*)); eargv = eargv_base; eargc = 0; - push_words(emulator); + PUSH(strsave(emulator)); eargc_base = eargc; eargv = eargv + eargv_size/2; eargc = 0; @@ -192,26 +194,6 @@ main(int argc, char** argv) return run_erlang(eargv[0], eargv); } -static void -push_words(char* src) -{ - char sbuf[MAXPATHLEN]; - char* dst; - - dst = sbuf; - while ((*dst++ = *src++) != '\0') { - if (isspace((int)*src)) { - *dst = '\0'; - PUSH(strsave(sbuf)); - dst = sbuf; - do { - src++; - } while (isspace((int)*src)); - } - } - if (sbuf[0]) - PUSH(strsave(sbuf)); -} #ifdef __WIN32__ wchar_t *make_commandline(char **argv) { diff --git a/erts/include/internal/ethread.h b/erts/include/internal/ethread.h index f9c203e97c..8964f95652 100644 --- a/erts/include/internal/ethread.h +++ b/erts/include/internal/ethread.h @@ -54,7 +54,8 @@ #endif #if defined(ETHR_DEBUG) || !defined(ETHR_INLINE) || ETHR_XCHK \ - || (defined(__GNUC__) && defined(ERTS_MIXED_CYGWIN_VC)) + || (defined(__GNUC__) && defined(ERTS_MIXED_CYGWIN_VC)) \ + || (defined(__GNUC__) && defined(ERTS_MIXED_MSYS_VC)) # undef ETHR_INLINE # define ETHR_INLINE # undef ETHR_FORCE_INLINE diff --git a/erts/preloaded/ebin/init.beam b/erts/preloaded/ebin/init.beam Binary files differindex 851513b2e9..73dfb3d351 100644 --- a/erts/preloaded/ebin/init.beam +++ b/erts/preloaded/ebin/init.beam diff --git a/erts/preloaded/src/init.erl b/erts/preloaded/src/init.erl index c4e37b76f1..0ad5824ad1 100644 --- a/erts/preloaded/src/init.erl +++ b/erts/preloaded/src/init.erl @@ -167,7 +167,6 @@ stop(Status) -> init ! {stop,{stop,Status}}, ok. boot(BootArgs) -> register(init, self()), process_flag(trap_exit, true), - start_on_load_handler_process(), {Start0,Flags,Args} = parse_boot_args(BootArgs), Start = map(fun prepare_run_args/1, Start0), Flags0 = flags_to_atoms_again(Flags), @@ -225,6 +224,7 @@ code_path_choice() -> end. boot(Start,Flags,Args) -> + start_on_load_handler_process(), BootPid = do_boot(Flags,Start), State = #state{flags = Flags, args = Args, diff --git a/lib/asn1/src/asn1rtt_ber.erl b/lib/asn1/src/asn1rtt_ber.erl index 39fa8aaf99..e50b14941c 100644 --- a/lib/asn1/src/asn1rtt_ber.erl +++ b/lib/asn1/src/asn1rtt_ber.erl @@ -739,6 +739,8 @@ encode_named_bit_string([H|_]=Bits, NamedBitList, TagIn) when is_atom(H) -> do_encode_named_bit_string(Bits, NamedBitList, TagIn); encode_named_bit_string([{bit,_}|_]=Bits, NamedBitList, TagIn) -> do_encode_named_bit_string(Bits, NamedBitList, TagIn); +encode_named_bit_string([], _NamedBitList, TagIn) -> + encode_unnamed_bit_string(<<>>, TagIn); encode_named_bit_string(Bits, _NamedBitList, TagIn) when is_bitstring(Bits) -> encode_unnamed_bit_string(Bits, TagIn). @@ -746,6 +748,8 @@ encode_named_bit_string(C, [H|_]=Bits, NamedBitList, TagIn) when is_atom(H) -> do_encode_named_bit_string(C, Bits, NamedBitList, TagIn); encode_named_bit_string(C, [{bit,_}|_]=Bits, NamedBitList, TagIn) -> do_encode_named_bit_string(C, Bits, NamedBitList, TagIn); +encode_named_bit_string(C, [], _NamedBitList, TagIn) -> + encode_unnamed_bit_string(C, <<>>, TagIn); encode_named_bit_string(C, Bits, _NamedBitList, TagIn) when is_bitstring(Bits) -> encode_unnamed_bit_string(C, Bits, TagIn). diff --git a/lib/asn1/test/testPrimStrings.erl b/lib/asn1/test/testPrimStrings.erl index fa778765b1..46793c6bff 100644 --- a/lib/asn1/test/testPrimStrings.erl +++ b/lib/asn1/test/testPrimStrings.erl @@ -123,6 +123,7 @@ bit_string(Rules, Opts) -> %% Bs2 ::= BIT STRING {su(0), mo(1), tu(2), we(3), th(4), fr(5), sa(6) } (SIZE (7)) %%========================================================== + roundtrip('Bs2', []), roundtrip('Bs2', [mo,tu,fr]), bs_roundtrip('Bs2', <<2#0110010:7>>, [mo,tu,fr]), bs_roundtrip('Bs2', <<2#0110011:7>>, [mo,tu,fr,sa]), @@ -131,6 +132,7 @@ bit_string(Rules, Opts) -> %% Bs3 ::= BIT STRING {su(0), mo(1), tu(2), we(3), th(4), fr(5), sa(6) } (SIZE (1..7)) %%========================================================== + roundtrip('Bs3', []), roundtrip('Bs3', [mo,tu,fr]), bs_roundtrip('Bs3', <<2#0110010:7>>, [mo,tu,fr]), bs_roundtrip('Bs3', <<2#0110010:7>>, [mo,tu,fr]), @@ -139,6 +141,13 @@ bit_string(Rules, Opts) -> bs_roundtrip('Bs3', <<2#11:2>>, [su,mo]), %%========================================================== + %% Bs4 ::= BIT STRING {su(0), mo(1), tu(2), we(3), th(4), fr(5), sa(6) } + %%========================================================== + + roundtrip('Bs4', []), + roundtrip('Bs4', [mo,tu,fr,sa]), + + %%========================================================== %% Bs7 ::= BIT STRING (SIZE (24)) %%========================================================== diff --git a/lib/common_test/src/ct_conn_log_h.erl b/lib/common_test/src/ct_conn_log_h.erl index 2dd4fdac05..5239ec1ff8 100644 --- a/lib/common_test/src/ct_conn_log_h.erl +++ b/lib/common_test/src/ct_conn_log_h.erl @@ -104,18 +104,26 @@ terminate(_,#state{logs=Logs}) -> %%%----------------------------------------------------------------- %%% Writing reports write_report(_Time,#conn_log{header=false,module=ConnMod}=Info,Data,GL,State) -> - {LogType,Fd} = get_log(Info,GL,State), - io:format(Fd,"~n~ts",[format_data(ConnMod,LogType,Data)]); + case get_log(Info,GL,State) of + {silent,_} -> + ok; + {LogType,Fd} -> + io:format(Fd,"~n~ts",[format_data(ConnMod,LogType,Data)]) + end; write_report(Time,#conn_log{module=ConnMod}=Info,Data,GL,State) -> - {LogType,Fd} = get_log(Info,GL,State), - io:format(Fd,"~n~ts~ts~ts",[format_head(ConnMod,LogType,Time), - format_title(LogType,Info), - format_data(ConnMod,LogType,Data)]). + case get_log(Info,GL,State) of + {silent,_} -> + ok; + {LogType,Fd} -> + io:format(Fd,"~n~ts~ts~ts",[format_head(ConnMod,LogType,Time), + format_title(LogType,Info), + format_data(ConnMod,LogType,Data)]) + end. write_error(Time,#conn_log{module=ConnMod}=Info,Report,GL,State) -> case get_log(Info,GL,State) of - {html,_} -> + {LogType,_} when LogType==html; LogType==silent -> %% The error will anyway be written in the html log by the %% sasl error handler, so don't write it again. ok; diff --git a/lib/common_test/src/ct_netconfc.erl b/lib/common_test/src/ct_netconfc.erl index 0de7bf03af..05977e5649 100644 --- a/lib/common_test/src/ct_netconfc.erl +++ b/lib/common_test/src/ct_netconfc.erl @@ -1272,6 +1272,14 @@ set_request_timer(T) -> {ok,TRef} = timer:send_after(T,{Ref,timeout}), {Ref,TRef}. +%%%----------------------------------------------------------------- +cancel_request_timer(undefined,undefined) -> + ok; +cancel_request_timer(Ref,TRef) -> + _ = timer:cancel(TRef), + receive {Ref,timeout} -> ok + after 0 -> ok + end. %%%----------------------------------------------------------------- client_hello(Options) when is_list(Options) -> @@ -1404,9 +1412,9 @@ handle_error(Reason, State) -> Pending -> %% Assuming the first request gets the %% first answer - P=#pending{tref=TRef,caller=Caller} = + P=#pending{tref=TRef,ref=Ref,caller=Caller} = lists:last(Pending), - _ = timer:cancel(TRef), + cancel_request_timer(Ref,TRef), Reason1 = {failed_to_parse_received_data,Reason}, ct_gen_conn:return(Caller,{error,Reason1}), lists:delete(P,Pending) @@ -1492,8 +1500,8 @@ decode({Tag,Attrs,_}=E, #state{connection=Connection,pending=Pending}=State) -> {error,Reason} -> {noreply,State#state{hello_status = {error,Reason}}} end; - #pending{tref=TRef,caller=Caller} -> - _ = timer:cancel(TRef), + #pending{tref=TRef,ref=Ref,caller=Caller} -> + cancel_request_timer(Ref,TRef), case decode_hello(E) of {ok,SessionId,Capabilities} -> ct_gen_conn:return(Caller,ok), @@ -1519,9 +1527,8 @@ decode({Tag,Attrs,_}=E, #state{connection=Connection,pending=Pending}=State) -> %% there is just one pending that matches (i.e. has %% undefined msg_id and op) case [P || P = #pending{msg_id=undefined,op=undefined} <- Pending] of - [#pending{tref=TRef, - caller=Caller}] -> - _ = timer:cancel(TRef), + [#pending{tref=TRef,ref=Ref,caller=Caller}] -> + cancel_request_timer(Ref,TRef), ct_gen_conn:return(Caller,E), {noreply,State#state{pending=[]}}; _ -> @@ -1542,8 +1549,8 @@ get_msg_id(Attrs) -> decode_rpc_reply(MsgId,{_,Attrs,Content0}=E,#state{pending=Pending} = State) -> case lists:keytake(MsgId,#pending.msg_id,Pending) of - {value, #pending{tref=TRef,op=Op,caller=Caller}, Pending1} -> - _ = timer:cancel(TRef), + {value, #pending{tref=TRef,ref=Ref,op=Op,caller=Caller}, Pending1} -> + cancel_request_timer(Ref,TRef), Content = forward_xmlns_attr(Attrs,Content0), {CallerReply,{ServerReply,State2}} = do_decode_rpc_reply(Op,Content,State#state{pending=Pending1}), @@ -1555,10 +1562,11 @@ decode_rpc_reply(MsgId,{_,Attrs,Content0}=E,#state{pending=Pending} = State) -> %% pending that matches (i.e. has undefined msg_id and op) case [P || P = #pending{msg_id=undefined,op=undefined} <- Pending] of [#pending{tref=TRef, + ref=Ref, msg_id=undefined, op=undefined, caller=Caller}] -> - _ = timer:cancel(TRef), + cancel_request_timer(Ref,TRef), ct_gen_conn:return(Caller,E), {noreply,State#state{pending=[]}}; _ -> diff --git a/lib/common_test/test/ct_netconfc_SUITE_data/netconfc1_SUITE.erl b/lib/common_test/test/ct_netconfc_SUITE_data/netconfc1_SUITE.erl index 64ebfbc463..aaa0723488 100644 --- a/lib/common_test/test/ct_netconfc_SUITE_data/netconfc1_SUITE.erl +++ b/lib/common_test/test/ct_netconfc_SUITE_data/netconfc1_SUITE.erl @@ -73,6 +73,7 @@ all() -> timeout_close_session, get, timeout_get, + flush_timeout_get, get_xpath, get_config, get_config_xpath, @@ -360,6 +361,28 @@ timeout_get(Config) -> ?ok = ct_netconfc:close_session(Client), ok. +%% Test OTP-13008 "ct_netconfc crash when receiving unknown timeout" +%% If the timer expires "at the same time" as the rpc reply is +%% received, the timeout message might already be sent when the timer +%% is cancelled. This test checks that the timeout message is flushed +%% from the message queue. If it isn't, the client crashes and the +%% session can not be closed afterwards. +%% Note that we can only hope that the test case triggers the problem +%% every now and then, as it is very timing dependent... +flush_timeout_get(Config) -> + DataDir = ?config(data_dir,Config), + {ok,Client} = open_success(DataDir), + Data = [{server,[{xmlns,"myns"}],[{name,[],["myserver"]}]}], + ?NS:expect_reply('get',{data,Data}), + timer:sleep(1000), + case ct_netconfc:get(Client,{server,[{xmlns,"myns"}],[]},1) of + {error,timeout} -> ok; % problem not triggered + {ok,Data} -> ok % problem possibly triggered + end, + ?NS:expect_do_reply('close-session',close,ok), + ?ok = ct_netconfc:close_session(Client), + ok. + get_xpath(Config) -> DataDir = ?config(data_dir,Config), {ok,Client} = open_success(DataDir), diff --git a/lib/compiler/doc/src/notes.xml b/lib/compiler/doc/src/notes.xml index bd85f22462..daf3bd3af9 100644 --- a/lib/compiler/doc/src/notes.xml +++ b/lib/compiler/doc/src/notes.xml @@ -458,22 +458,28 @@ <p> EEP43: New data type - Maps</p> <p> - With Maps you may for instance: <taglist> <item><c>M0 = - #{ a => 1, b => 2}, % create - associations</c></item> <item><c>M1 = M0#{ a := 10 }, % - update values</c></item> <item><c>M2 = M1#{ "hi" => - "hello"}, % add new associations</c></item> <item><c>#{ - "hi" := V1, a := V2, b := V3} = M2. % match keys with - values</c></item> </taglist></p> + With Maps you may for instance:</p> + <taglist> + <tag/> <item><c>M0 = #{ a => 1, b => 2}, % create + associations</c></item> + <tag/><item><c>M1 = M0#{ a := 10 }, % update values</c></item> + <tag/><item><c>M2 = M1#{ "hi" => + "hello"}, % add new associations</c></item> + <tag/><item><c>#{ "hi" := V1, a := V2, b := V3} = M2. + % match keys with values</c></item> + </taglist> <p> For information on how to use Maps please see Map Expressions in the <seealso marker="doc/reference_manual:expressions#map_expressions"> Reference Manual</seealso>.</p> <p> The current implementation is without the following - features: <taglist> <item>No variable keys</item> - <item>No single value access</item> <item>No map - comprehensions</item> </taglist></p> + features:</p> + <taglist> + <tag/><item>No variable keys</item> + <tag/><item>No single value access</item> + <tag/><item>No map comprehensions</item> + </taglist> <p> Note that Maps is <em>experimental</em> during OTP 17.0.</p> <p> diff --git a/lib/compiler/src/sys_core_fold.erl b/lib/compiler/src/sys_core_fold.erl index 27d023d067..65699ccda9 100644 --- a/lib/compiler/src/sys_core_fold.erl +++ b/lib/compiler/src/sys_core_fold.erl @@ -3091,12 +3091,12 @@ bsm_ensure_no_partition_2([#c_var{name=V}|Ps], N, G, Vstate, S) -> bsm_ensure_no_partition_2([_|Ps], N, G, _, S) -> bsm_ensure_no_partition_2(Ps, N-1, G, bin_argument_order, S). -bsm_ensure_no_partition_after([#c_clause{pats=Ps}|Cs], Pos) -> +bsm_ensure_no_partition_after([#c_clause{pats=Ps}=C|Cs], Pos) -> case nth(Pos, Ps) of #c_var{} -> bsm_ensure_no_partition_after(Cs, Pos); - P -> - bsm_problem(P, bin_partition) + _ -> + bsm_problem(C, bin_partition) end; bsm_ensure_no_partition_after([], _) -> ok. diff --git a/lib/compiler/test/bs_match_SUITE.erl b/lib/compiler/test/bs_match_SUITE.erl index 6e138b0a43..b4601b0798 100644 --- a/lib/compiler/test/bs_match_SUITE.erl +++ b/lib/compiler/test/bs_match_SUITE.erl @@ -36,7 +36,7 @@ match_string/1,zero_width/1,bad_size/1,haystack/1, cover_beam_bool/1,matched_out_size/1,follow_fail_branch/1, no_partition/1,calling_a_binary/1,binary_in_map/1, - match_string_opt/1]). + match_string_opt/1,map_and_binary/1]). -export([coverage_id/1,coverage_external_ignore/2]). @@ -62,7 +62,7 @@ groups() -> otp_7498,match_string,zero_width,bad_size,haystack, cover_beam_bool,matched_out_size,follow_fail_branch, no_partition,calling_a_binary,binary_in_map, - match_string_opt]}]. + match_string_opt,map_and_binary]}]. init_per_suite(Config) -> @@ -1225,6 +1225,24 @@ match_string_opt(Config) when is_list(Config) -> do_match_string_opt({<<1>>,{v,V}}=T) -> {x,V,T}. +%% If 'bin_opt_info' was given the warning would lack filename +%% and line number. + +map_and_binary(_Config) -> + {<<"10">>,<<"37">>,<<"am">>} = do_map_and_binary(<<"10:37am">>), + Map1 = #{time => "noon"}, + {ok,Map1} = do_map_and_binary(Map1), + Map2 = #{hour => 8, min => 42}, + {8,42,Map2} = do_map_and_binary(Map2), + ok. + +do_map_and_binary(<<Hour:2/bytes, $:, Min:2/bytes, Rest/binary>>) -> + {Hour, Min, Rest}; +do_map_and_binary(#{time := _} = T) -> + {ok, T}; +do_map_and_binary(#{hour := Hour, min := Min} = T) -> + {Hour, Min, T}. + check(F, R) -> R = F(). diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml index 291a5145e4..563a090e98 100644 --- a/lib/crypto/doc/src/crypto.xml +++ b/lib/crypto/doc/src/crypto.xml @@ -66,29 +66,29 @@ <section> <title>DATA TYPES </title> - <p><code>key_value() = integer() | binary() </code></p> + <code>key_value() = integer() | binary() </code> <p>Always <c>binary()</c> when used as return value</p> - <p><code>rsa_public() = [key_value()] = [E, N] </code></p> + <code>rsa_public() = [key_value()] = [E, N] </code> <p> Where E is the public exponent and N is public modulus. </p> - <p><code>rsa_private() = [key_value()] = [E, N, D] | [E, N, D, P1, P2, E1, E2, C] </code></p> + <code>rsa_private() = [key_value()] = [E, N, D] | [E, N, D, P1, P2, E1, E2, C] </code> <p>Where E is the public exponent, N is public modulus and D is the private exponent.The longer key format contains redundant information that will make the calculation faster. P1,P2 are first and second prime factors. E1,E2 are first and second exponents. C is the CRT coefficient. Terminology is taken from <url href="http://www.ietf.org/rfc/rfc3477.txt"> RFC 3447</url>.</p> - <p><code>dss_public() = [key_value()] = [P, Q, G, Y] </code></p> + <code>dss_public() = [key_value()] = [P, Q, G, Y] </code> <p>Where P, Q and G are the dss parameters and Y is the public key.</p> - <p><code>dss_private() = [key_value()] = [P, Q, G, X] </code></p> + <code>dss_private() = [key_value()] = [P, Q, G, X] </code> <p>Where P, Q and G are the dss parameters and X is the private key.</p> - <p><code>srp_public() = key_value() </code></p> + <code>srp_public() = key_value() </code> <p>Where is <c>A</c> or <c>B</c> from <url href="http://srp.stanford.edu/design.html">SRP design</url></p> - <p><code>srp_private() = key_value() </code></p> + <code>srp_private() = key_value() </code> <p>Where is <c>a</c> or <c>b</c> from <url href="http://srp.stanford.edu/design.html">SRP design</url></p> <p>Where Verifier is <c>v</c>, Generator is <c>g</c> and Prime is<c> N</c>, DerivedKey is <c>X</c>, and Scrambler is @@ -96,29 +96,29 @@ Version = '3' | '6' | '6a' </p> - <p><code>dh_public() = key_value() </code></p> + <code>dh_public() = key_value() </code> - <p><code>dh_private() = key_value() </code></p> + <code>dh_private() = key_value() </code> - <p><code>dh_params() = [key_value()] = [P, G] </code></p> + <code>dh_params() = [key_value()] = [P, G] </code> - <p><code>ecdh_public() = key_value() </code></p> + <code>ecdh_public() = key_value() </code> - <p><code>ecdh_private() = key_value() </code></p> + <code>ecdh_private() = key_value() </code> - <p><code>ecdh_params() = ec_named_curve() | ec_explicit_curve()</code></p> + <code>ecdh_params() = ec_named_curve() | ec_explicit_curve()</code> - <p><code>ec_explicit_curve() = - {ec_field(), Prime :: key_value(), Point :: key_value(), Order :: integer(), CoFactor :: none | integer()} </code></p> + <code>ec_explicit_curve() = + {ec_field(), Prime :: key_value(), Point :: key_value(), Order :: integer(), CoFactor :: none | integer()} </code> - <p><code>ec_field() = {prime_field, Prime :: integer()} | - {characteristic_two_field, M :: integer(), Basis :: ec_basis()}</code></p> + <code>ec_field() = {prime_field, Prime :: integer()} | + {characteristic_two_field, M :: integer(), Basis :: ec_basis()}</code> - <p><code>ec_basis() = {tpbasis, K :: non_neg_integer()} | + <code>ec_basis() = {tpbasis, K :: non_neg_integer()} | {ppbasis, K1 :: non_neg_integer(), K2 :: non_neg_integer(), K3 :: non_neg_integer()} | - onbasis</code></p> + onbasis</code> - <p><code>ec_named_curve() -> + <code>ec_named_curve() -> sect571r1| sect571k1| sect409r1| sect409k1| secp521r1| secp384r1| secp224r1| secp224k1| secp192k1| secp160r2| secp128r2| secp128r1| sect233r1| sect233k1| sect193r2| sect193r1| sect131r2| sect131r1| sect283r1| sect283k1| sect163r2| secp256k1| secp160k1| secp160r1| @@ -128,42 +128,42 @@ brainpoolP224t1| brainpoolP256r1| brainpoolP256t1| brainpoolP320r1| brainpoolP320t1| brainpoolP384r1| brainpoolP384t1| brainpoolP512r1| brainpoolP512t1 </code> - Note that the <em>sect</em> curves are GF2m (characteristic two) curves and are only supported if the + <p>Note that the <em>sect</em> curves are GF2m (characteristic two) curves and are only supported if the underlying OpenSSL has support for them. See also <seealso marker="#supports-0">crypto:supports/0</seealso> </p> - <p><code>stream_cipher() = rc4 | aes_ctr </code></p> + <code>stream_cipher() = rc4 | aes_ctr </code> - <p><code>block_cipher() = aes_cbc128 | aes_cfb8 | aes_cfb128 | aes_ige256 | blowfish_cbc | + <code>block_cipher() = aes_cbc128 | aes_cfb8 | aes_cfb128 | aes_ige256 | blowfish_cbc | blowfish_cfb64 | des_cbc | des_cfb | des3_cbc | des3_cbf - | des_ede3 | rc2_cbc </code></p> + | des_ede3 | rc2_cbc </code> - <p><code>aead_cipher() = aes_gcm | chacha20_poly1305 </code></p> + <code>aead_cipher() = aes_gcm | chacha20_poly1305 </code> - <p><code>stream_key() = aes_key() | rc4_key() </code></p> + <code>stream_key() = aes_key() | rc4_key() </code> - <p><code>block_key() = aes_key() | blowfish_key() | des_key()| des3_key() </code></p> + <code>block_key() = aes_key() | blowfish_key() | des_key()| des3_key() </code> - <p><code>aes_key() = iodata() </code> Key length is 128, 192 or 256 bits</p> + <code>aes_key() = iodata() </code> <p>Key length is 128, 192 or 256 bits</p> - <p><code>rc4_key() = iodata() </code> Variable key length from 8 bits up to 2048 bits (usually between 40 and 256)</p> + <code>rc4_key() = iodata() </code> <p>Variable key length from 8 bits up to 2048 bits (usually between 40 and 256)</p> - <p><code>blowfish_key() = iodata() </code> Variable key length from 32 bits up to 448 bits</p> + <code>blowfish_key() = iodata() </code> <p>Variable key length from 32 bits up to 448 bits</p> - <p><code>des_key() = iodata() </code> Key length is 64 bits (in CBC mode only 8 bits are used)</p> + <code>des_key() = iodata() </code> <p>Key length is 64 bits (in CBC mode only 8 bits are used)</p> - <p><code>des3_key() = [binary(), binary(), binary()] </code> Each key part is 64 bits (in CBC mode only 8 bits are used)</p> + <code>des3_key() = [binary(), binary(), binary()] </code> <p>Each key part is 64 bits (in CBC mode only 8 bits are used)</p> - <p><code>digest_type() = md5 | sha | sha224 | sha256 | sha384 | sha512</code></p> + <code>digest_type() = md5 | sha | sha224 | sha256 | sha384 | sha512</code> - <p><code> hash_algorithms() = md5 | ripemd160 | sha | sha224 | sha256 | sha384 | sha512 </code> md4 is also supported for hash_init/1 and hash/2. + <code> hash_algorithms() = md5 | ripemd160 | sha | sha224 | sha256 | sha384 | sha512 </code> <p>md4 is also supported for hash_init/1 and hash/2. Note that both md4 and md5 are recommended only for compatibility with existing applications. </p> - <p><code> cipher_algorithms() = des_cbc | des_cfb | des3_cbc | des3_cbf | des_ede3 | - blowfish_cbc | blowfish_cfb64 | aes_cbc128 | aes_cfb8 | aes_cfb128| aes_cbc256 | aes_ige256 | aes_gcm | chacha20_poly1305 | rc2_cbc | aes_ctr| rc4 </code> </p> - <p><code> public_key_algorithms() = rsa |dss | ecdsa | dh | ecdh | ec_gf2m</code> - Note that ec_gf2m is not strictly a public key algorithm, but a restriction on what curves are supported + <code> cipher_algorithms() = des_cbc | des_cfb | des3_cbc | des3_cbf | des_ede3 | + blowfish_cbc | blowfish_cfb64 | aes_cbc128 | aes_cfb8 | aes_cfb128| aes_cbc256 | aes_ige256 | aes_gcm | chacha20_poly1305 | rc2_cbc | aes_ctr| rc4 </code> + <code> public_key_algorithms() = rsa |dss | ecdsa | dh | ecdh | ec_gf2m</code> + <p>Note that ec_gf2m is not strictly a public key algorithm, but a restriction on what curves are supported with ecdsa and ecdh. </p> @@ -381,8 +381,8 @@ </type> <desc> <p>Computes a HMAC of type <c>Type</c> from <c>Data</c> using - <c>Key</c> as the authentication key.</p> <c>MacLength</c> - will limit the size of the resultant <c>Mac</c>. + <c>Key</c> as the authentication key.</p> <p><c>MacLength</c> + will limit the size of the resultant <c>Mac</c>.</p> </desc> </func> @@ -601,8 +601,11 @@ </type> <desc> <p>Generates N bytes randomly uniform 0..255, and returns the - result in a binary. Uses the <c>crypto</c> library pseudo-random - number generator.</p> + result in a binary. Uses the <c>crypto</c> library pseudo-random + number generator.</p> + <p>This function is not recommended for cryptographic purposes. + Please use <seealso marker="#strong_rand_bytes/1"> + strong_rand_bytes/1</seealso> instead.</p> </desc> </func> @@ -650,7 +653,7 @@ <p>Creates a digital signature.</p> <p>Algorithm <c>dss</c> can only be used together with digest type <c>sha</c>.</p> - See also <seealso marker="public_key:public_key#sign-3">public_key:sign/3</seealso> + <p>See also <seealso marker="public_key:public_key#sign-3">public_key:sign/3</seealso>.</p> </desc> </func> @@ -802,7 +805,7 @@ <p>Algorithm <c>dss</c> can only be used together with digest type <c>sha</c>.</p> - See also <seealso marker="public_key:public_key#verify-4">public_key:verify/4</seealso> + <p>See also <seealso marker="public_key:public_key#verify-4">public_key:verify/4</seealso>.</p> </desc> </func> diff --git a/lib/erl_docgen/priv/dtd/cites.dtd b/lib/erl_docgen/priv/dtd/cites.dtd index 73931af009..4558947db0 100644 --- a/lib/erl_docgen/priv/dtd/cites.dtd +++ b/lib/erl_docgen/priv/dtd/cites.dtd @@ -30,7 +30,7 @@ <!ELEMENT cite (id, shortdef, def, resp?) > <!ELEMENT id (#PCDATA) > <!ELEMENT shortdef (#PCDATA) > -<!ELEMENT def (#PCDATA|c|em)* > +<!ELEMENT def (#PCDATA|c|i|em)* > <!ELEMENT resp (#PCDATA) > <!ELEMENT c (#PCDATA) > <!ELEMENT em (#PCDATA|c)* > diff --git a/lib/erl_docgen/priv/dtd/common.dtd b/lib/erl_docgen/priv/dtd/common.dtd index ded16d308f..a29fc233fa 100644 --- a/lib/erl_docgen/priv/dtd/common.dtd +++ b/lib/erl_docgen/priv/dtd/common.dtd @@ -24,21 +24,23 @@ <!ENTITY % block "p|pre|code|list|taglist|codeinclude| erleval" > -<!ENTITY % inline "#PCDATA|c|em|term|cite|br|path|seealso| - url|marker" > +<!ENTITY % inline "#PCDATA|c|i|em|term|cite|br|path|seealso| + url|marker|anno" > <!-- XXX --> <!ELEMENT p (%inline;)* > -<!ELEMENT pre (#PCDATA|seealso|url|input)* > -<!ELEMENT input (#PCDATA|seealso|url)* > -<!ELEMENT code (#PCDATA) > +<!ELEMENT pre (#PCDATA|seealso|url|input|anno)* > +<!ELEMENT input (#PCDATA|seealso|url|anno)* > +<!ELEMENT code (#PCDATA|anno)* > <!ATTLIST code type (erl|c|none) "none" > <!ELEMENT quote (p)* > <!ELEMENT warning (%block;|quote|br|marker)* > <!ELEMENT note (%block;|quote|br|marker)* > <!ELEMENT dont (%block;|quote|br|marker)* > <!ELEMENT do (%block;|quote|br|marker)* > -<!ELEMENT c (#PCDATA) > -<!ELEMENT em (#PCDATA|c)* > +<!ELEMENT c (#PCDATA|anno)* > +<!ELEMENT i (#PCDATA|c|anno)* > +<!ELEMENT em (#PCDATA|c|anno)* > +<!ELEMENT anno (#PCDATA) > <!-- XXX --> <!ELEMENT term (termdef?) > @@ -64,13 +66,13 @@ <!ELEMENT list (item+) > <!ATTLIST list type (ordered|bulleted) "bulleted" > -<!ELEMENT taglist (tag,item)+ > -<!ELEMENT tag (#PCDATA|c|em|seealso|url|marker)* > +<!ELEMENT taglist (tag,item+)+ > +<!ELEMENT tag (#PCDATA|c|i|em|br|seealso|url|marker|anno)* > <!ELEMENT item (%inline;|%block;)* > <!-- References --> -<!ELEMENT seealso (#PCDATA|c|em)* > +<!ELEMENT seealso (#PCDATA|c|i|em|anno)* > <!ATTLIST seealso marker CDATA #REQUIRED > <!ELEMENT url (#PCDATA) > <!ATTLIST url href CDATA #REQUIRED > diff --git a/lib/erl_docgen/priv/dtd/common.header.dtd b/lib/erl_docgen/priv/dtd/common.header.dtd index 71a8662572..eb27dc8f97 100644 --- a/lib/erl_docgen/priv/dtd/common.header.dtd +++ b/lib/erl_docgen/priv/dtd/common.header.dtd @@ -18,8 +18,8 @@ $Id$ --> <!ELEMENT header (copyright?,legalnotice?,title,shorttitle?, - prepared,responsible?,docno,approved?, - checked?,date,rev,file?) > + prepared?,responsible?,docno?,approved?, + checked?,date?,rev?,file?) > <!-- The titlestyle attribute is only defined to make all the book.xml files diff --git a/lib/erl_docgen/priv/dtd/common.refs.dtd b/lib/erl_docgen/priv/dtd/common.refs.dtd index f57e46a624..6889e990de 100644 --- a/lib/erl_docgen/priv/dtd/common.refs.dtd +++ b/lib/erl_docgen/priv/dtd/common.refs.dtd @@ -27,15 +27,16 @@ <!ELEMENT description (%block;|quote|br|marker|warning|note|dont|do)* > <!ELEMENT funcs (func)+ > -<!ELEMENT func (name+,type_desc*,fsummary,type?,desc?) > +<!ELEMENT func (name+,fsummary,(type|type_desc)*,desc?) > <!-- ELEMENT name is defined in each ref dtd --> -<!ELEMENT fsummary (#PCDATA|c|em)* > +<!ELEMENT fsummary (#PCDATA|c|i|em|anno)* > <!ELEMENT type (v,d?)* > <!ATTLIST type variable CDATA #IMPLIED + name CDATA #IMPLIED name_i CDATA #IMPLIED> -<!ELEMENT v (#PCDATA) > -<!ELEMENT d (#PCDATA|c|em)* > -<!ELEMENT desc (%block;|quote|br|marker|warning|note|dont|do|anno)* > +<!ELEMENT v (#PCDATA|seealso)* > +<!ELEMENT d (#PCDATA|c|i|em)* > +<!ELEMENT desc (%block;|quote|br|marker|warning|note|dont|do)* > <!ELEMENT authors (aname,email)+ > <!ELEMENT aname (#PCDATA) > <!ELEMENT email (#PCDATA) > @@ -43,5 +44,6 @@ warning|note|dont|do)*) > <!ELEMENT datatypes (datatype)+ > <!ELEMENT datatype (name+,desc?) > -<!ELEMENT type_desc (#PCDATA) > -<!ATTLIST type_desc variable CDATA #REQUIRED> +<!ELEMENT type_desc (#PCDATA|anno|c|seealso)* > +<!ATTLIST type_desc variable CDATA #IMPLIED + name CDATA #IMPLIED> diff --git a/lib/erl_docgen/priv/dtd/erlref.dtd b/lib/erl_docgen/priv/dtd/erlref.dtd index d62e2a5fcb..835407520a 100644 --- a/lib/erl_docgen/priv/dtd/erlref.dtd +++ b/lib/erl_docgen/priv/dtd/erlref.dtd @@ -32,4 +32,5 @@ <!ELEMENT name (#PCDATA) > <!ATTLIST name name CDATA #IMPLIED arity CDATA #IMPLIED - clause_i CDATA #IMPLIED> + clause_i CDATA #IMPLIED + n_vars CDATA #IMPLIED> diff --git a/lib/erl_docgen/priv/dtd/terms.dtd b/lib/erl_docgen/priv/dtd/terms.dtd index fd160b5c02..c2965eb61c 100644 --- a/lib/erl_docgen/priv/dtd/terms.dtd +++ b/lib/erl_docgen/priv/dtd/terms.dtd @@ -30,7 +30,7 @@ <!ELEMENT term (id, shortdef, def, resp?) > <!ELEMENT id (#PCDATA) > <!ELEMENT shortdef (#PCDATA) > -<!ELEMENT def (#PCDATA|c|em)* > +<!ELEMENT def (#PCDATA|c|i|em)* > <!ELEMENT resp (#PCDATA) > <!ELEMENT c (#PCDATA) > <!ELEMENT em (#PCDATA|c)* > diff --git a/lib/erl_docgen/priv/xsl/db_html.xsl b/lib/erl_docgen/priv/xsl/db_html.xsl index f5ddd364d3..c2325fbee9 100644 --- a/lib/erl_docgen/priv/xsl/db_html.xsl +++ b/lib/erl_docgen/priv/xsl/db_html.xsl @@ -990,12 +990,15 @@ </p> </xsl:template> - <!-- Inline elements --> <xsl:template match="b"> <strong><xsl:apply-templates/></strong> </xsl:template> + <xsl:template match="i"> + <i><xsl:apply-templates/></i> + </xsl:template> + <xsl:template match="br"> <br/> </xsl:template> diff --git a/lib/erl_docgen/priv/xsl/db_man.xsl b/lib/erl_docgen/priv/xsl/db_man.xsl index 120bf9880d..5201465e42 100644 --- a/lib/erl_docgen/priv/xsl/db_man.xsl +++ b/lib/erl_docgen/priv/xsl/db_man.xsl @@ -595,6 +595,12 @@ <xsl:text>\fR\& </xsl:text> </xsl:template> + <xsl:template match="i"> + <xsl:text>\fI</xsl:text> + <xsl:apply-templates/> + <xsl:text>\fR\& </xsl:text> + </xsl:template> + <xsl:template match="br"> <xsl:choose> <xsl:when test="ancestor::head"> diff --git a/lib/erl_docgen/priv/xsl/db_pdf.xsl b/lib/erl_docgen/priv/xsl/db_pdf.xsl index 53e202d52c..37a2d55274 100644 --- a/lib/erl_docgen/priv/xsl/db_pdf.xsl +++ b/lib/erl_docgen/priv/xsl/db_pdf.xsl @@ -1186,6 +1186,12 @@ </fo:inline> </xsl:template> + <xsl:template match="i"> + <fo:inline font-weight="italic"> + <xsl:apply-templates/> + </fo:inline> + </xsl:template> + <xsl:template match="br"> <fo:block/> </xsl:template> diff --git a/lib/erl_docgen/src/docgen_edoc_xml_cb.erl b/lib/erl_docgen/src/docgen_edoc_xml_cb.erl index 03fc161c5a..0ac7985a48 100644 --- a/lib/erl_docgen/src/docgen_edoc_xml_cb.erl +++ b/lib/erl_docgen/src/docgen_edoc_xml_cb.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2001-2012. All Rights Reserved. +%% Copyright Ericsson AB 2001-2015. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -352,8 +352,8 @@ otp_xmlify_e(#xmlElement{name=code} = E) -> % 4) end; otp_xmlify_e(#xmlElement{name=Tag} = E) % 5a when Tag==h1; Tag==h2; Tag==h3; Tag==h4; Tag==h5 -> - Content = text_and_a_name_only(E#xmlElement.content), - [E#xmlElement{name=b, content=Content}]; + {Name, Text} = text_and_a_name_only(E#xmlElement.content), + [Name, E#xmlElement{name=b, content=Text}]; otp_xmlify_e(#xmlElement{name=Tag} = E) % 5b-c) when Tag==center; Tag==font -> @@ -1190,17 +1190,13 @@ get_text(#xmlElement{content=[#xmlText{value=Text}]}) -> get_text(#xmlElement{content=[E]}) -> get_text(E). -%% text_and_name_only(Es) -> Ts -text_and_a_name_only([#xmlElement{ - name = a, - attributes = [#xmlAttribute{name=name}]} = Name|Es]) -> - [Name|text_and_a_name_only(Es)]; -text_and_a_name_only([#xmlElement{content = Content}|Es]) -> - text_and_a_name_only(Content) ++ text_and_a_name_only(Es); -text_and_a_name_only([#xmlText{} = E |Es]) -> - [E | text_and_a_name_only(Es)]; -text_and_a_name_only([]) -> - []. +%% text_and_name_only(Es) -> {N, Ts} +text_and_a_name_only(Es) -> + [Name|_] = [Name || + #xmlElement{ + name = a, + attributes = [#xmlAttribute{name=name}]}=Name <- Es], + {Name#xmlElement{content = []}, text_only(Es)}. %% text_only(Es) -> Ts %% Takes a list of xmlElement and xmlText and return a lists of xmlText. diff --git a/lib/erl_docgen/vsn.mk b/lib/erl_docgen/vsn.mk index 2abd3d2b7e..43f5a570d7 100644 --- a/lib/erl_docgen/vsn.mk +++ b/lib/erl_docgen/vsn.mk @@ -1 +1 @@ -ERL_DOCGEN_VSN = 0.4 +ERL_DOCGEN_VSN = 0.4.1 diff --git a/lib/erl_interface/src/connect/ei_resolve.c b/lib/erl_interface/src/connect/ei_resolve.c index 3f1be2b17d..6381b02393 100644 --- a/lib/erl_interface/src/connect/ei_resolve.c +++ b/lib/erl_interface/src/connect/ei_resolve.c @@ -601,6 +601,16 @@ struct hostent *ei_gethostbyaddr(const char *addr, int len, int type) return gethostbyaddr(addr, len, type); } +/* + * Imprecise way to select the actually available gethostbyname_r and + * gethostbyaddr_r. + * + * TODO: check this properly in configure.in + */ +#if (defined(__linux__) || (__FreeBSD_version >= 602000) || defined(__DragonFly__)) + #define HAVE_GETHOSTBYADDR_R_8 1 +#endif + struct hostent *ei_gethostbyaddr_r(const char *addr, int length, int type, @@ -616,7 +626,7 @@ struct hostent *ei_gethostbyaddr_r(const char *addr, #ifndef HAVE_GETHOSTBYNAME_R return my_gethostbyaddr_r(addr,length,type,hostp,buffer,buflen,h_errnop); #else -#if (defined(__GLIBC__) || (__FreeBSD_version >= 602000) || defined(__DragonFly__)) +#ifdef HAVE_GETHOSTBYADDR_R_8 struct hostent *result; gethostbyaddr_r(addr, length, type, hostp, buffer, buflen, &result, @@ -643,7 +653,7 @@ struct hostent *ei_gethostbyname_r(const char *name, #ifndef HAVE_GETHOSTBYNAME_R return my_gethostbyname_r(name,hostp,buffer,buflen,h_errnop); #else -#if (defined(__GLIBC__) || (__FreeBSD_version >= 602000) || defined(__DragonFly__) || defined(__ANDROID__)) +#ifdef HAVE_GETHOSTBYADDR_R_8 struct hostent *result; gethostbyname_r(name, hostp, buffer, buflen, &result, h_errnop); diff --git a/lib/eunit/doc/overview.edoc b/lib/eunit/doc/overview.edoc index 2789a05792..12ea02f442 100644 --- a/lib/eunit/doc/overview.edoc +++ b/lib/eunit/doc/overview.edoc @@ -907,7 +907,6 @@ the test set is finished, regardless of the outcome (success, failures, timeouts, etc.). To make the descriptions simpler, we first list some definitions: -<center> <table border="0" cellspacing="4"> <tr> <td>`Setup'</td><td>`() -> (R::any())'</td> @@ -928,7 +927,6 @@ To make the descriptions simpler, we first list some definitions: <td>`Where'</td><td>`local | spawn | {spawn, Node::atom()}'</td> </tr> </table> -</center> (these are explained in more detail further below.) The following representations specify fixture handling for test sets: diff --git a/lib/eunit/include/eunit.hrl b/lib/eunit/include/eunit.hrl index 88e9d6c19b..8f678b0290 100644 --- a/lib/eunit/include/eunit.hrl +++ b/lib/eunit/include/eunit.hrl @@ -135,7 +135,6 @@ -define(_assertThrow(Term, Expr), ?_assertException(throw, Term, Expr)). -define(_assertNotException(Class, Term, Expr), ?_test(?assertNotException(Class, Term, Expr))). --define(_assertReceive(Guard, Expr), ?_test(?assertReceive(Guard, Expr))). %% Macros for running operating system commands. (Note that these %% require EUnit to be present at runtime, or at least eunit_lib.) diff --git a/lib/inets/src/http_client/httpc_handler.erl b/lib/inets/src/http_client/httpc_handler.erl index 1044cffe6f..d1c52dcc78 100644 --- a/lib/inets/src/http_client/httpc_handler.erl +++ b/lib/inets/src/http_client/httpc_handler.erl @@ -1113,8 +1113,8 @@ handle_http_body(Body, #state{headers = Headers, case case_insensitive_header(TransferEnc) of "chunked" -> ?hcrt("handle_http_body - chunked", []), - case http_chunk:decode(Body, State#state.max_body_size, - State#state.max_header_size) of + try http_chunk:decode(Body, State#state.max_body_size, + State#state.max_header_size) of {Module, Function, Args} -> ?hcrt("handle_http_body - new mfa", [{module, Module}, @@ -1139,6 +1139,13 @@ handle_http_body(Body, #state{headers = Headers, handle_response(State#state{headers = NewHeaders, body = NewBody2}) end + catch throw:{error, Reason} -> + NewState = + answer_request(Request, + httpc_response:error(Request, + Reason), + State), + {stop, normal, NewState} end; Enc when Enc =:= "identity"; Enc =:= undefined -> ?hcrt("handle_http_body - identity", []), @@ -1820,11 +1827,13 @@ host_header(_, URI) -> tls_upgrade(#state{status = {ssl_tunnel, #request{settings = - #http_options{ssl = {_, TLSOptions} = SocketType}, - address = Address} = Request}, + #http_options{ssl = {_, TLSOptions0} = SocketType}, + address = {Host, _} = Address} = Request}, session = #session{socket = TCPSocket} = Session0, options = Options} = State) -> + TLSOptions = maybe_add_sni(Host, TLSOptions0), + case ssl:connect(TCPSocket, TLSOptions) of {ok, TLSSocket} -> ClientClose = httpc_request:is_client_closing(Request#request.headers), @@ -1855,6 +1864,15 @@ tls_upgrade(#state{status = {stop, normal, State#state{request = Request}} end. +maybe_add_sni(Host, Options) -> + case http_util:is_hostname(Host) andalso + not lists:keymember(server_name_indication, 1, Options) of + true -> + [{server_name_indication, Host} | Options]; + false -> + Options + end. + %% --------------------------------------------------------------------- %% Session wrappers %% --------------------------------------------------------------------- diff --git a/lib/inets/src/http_lib/http_chunk.erl b/lib/inets/src/http_lib/http_chunk.erl index 2f8476a49d..7325f24809 100644 --- a/lib/inets/src/http_lib/http_chunk.erl +++ b/lib/inets/src/http_lib/http_chunk.erl @@ -25,7 +25,7 @@ -include("http_internal.hrl"). %% API --export([decode/3, encode/1, encode_last/0, handle_headers/2]). +-export([decode/3, encode/1, encode_last/0, encode_last/1, handle_headers/2]). %% Callback API - used for example if the chunkedbody is received a %% little at a time on a socket. -export([decode_size/1, ignore_extensions/1, decode_data/1, decode_trailer/1]). @@ -85,6 +85,11 @@ encode(Chunk) when is_list(Chunk)-> encode_last() -> <<$0, ?CR, ?LF, ?CR, ?LF >>. +encode_last([]) -> + encode_last(); +encode_last(Trailers0) -> + Trailers = list_to_binary(encode_trailers(Trailers0)), + <<$0, ?CR, ?LF, Trailers/binary>>. %%------------------------------------------------------------------------- %% handle_headers(HeaderRecord, ChunkedHeaders) -> NewHeaderRecord @@ -147,7 +152,7 @@ decode_size(Data = <<?CR, ?LF, ChunkRest/binary>>, HexList, AccHeaderSize, {MaxBodySize, Body, AccLength, MaxHeaderSize}) -> - try http_util:hexlist_to_integer(lists:reverse(HexList)) of + try http_util:hexlist_to_integer(lists:reverse(string:strip(HexList, left))) of 0 -> % Last chunk, there was no data ignore_extensions(Data, remaing_size(MaxHeaderSize, AccHeaderSize), MaxHeaderSize, {?MODULE, decode_trailer, @@ -276,10 +281,18 @@ decode_trailer(<<?CR, ?LF, Rest/binary>>, Header, Headers, Body, BodyLength, Rem Body, BodyLength, RemainingSize, TotalMaxHeaderSize); decode_trailer(<<Octet, Rest/binary>>, Header, Headers, Body, BodyLength, RemainingSize, TotalMaxHeaderSize) -> - decode_trailer(Rest, [Octet | Header], Headers, - Body, BodyLength, RemainingSize - 1, TotalMaxHeaderSize). + decode_trailer(Rest, [Octet | Header], Headers, + Body, BodyLength, remaing_size(RemainingSize, 1), TotalMaxHeaderSize). remaing_size(nolimit, _) -> nolimit; remaing_size(Total, Consumed) -> Total - Consumed. + +encode_trailers(Trailers) -> + encode_trailers(Trailers, ""). + +encode_trailers([], Acc) -> + Acc ++ ?CRLF ++ ?CRLF; +encode_trailers([{Header, Value} | Rest], Acc) -> + encode_trailers(Rest, Header ++ ":" ++ Value ++ ?CRLF ++ Acc). diff --git a/lib/inets/src/http_lib/http_response.erl b/lib/inets/src/http_lib/http_response.erl index d13670700c..42e5dd263d 100644 --- a/lib/inets/src/http_lib/http_response.erl +++ b/lib/inets/src/http_lib/http_response.erl @@ -65,6 +65,8 @@ header_list(Headers) -> %%%======================================================================== fill_headers([], _, Headers) -> Headers; +fill_headers([[]], _, Headers) -> + Headers; fill_headers([[Ch|HeaderFold]|Tail], Folded, Headers) when Ch == $\t; Ch == $\s -> fill_headers(Tail, [HeaderFold|Folded], Headers); diff --git a/lib/inets/src/http_server/httpd_example.erl b/lib/inets/src/http_server/httpd_example.erl index d729affd6d..0222487a4b 100644 --- a/lib/inets/src/http_server/httpd_example.erl +++ b/lib/inets/src/http_server/httpd_example.erl @@ -24,7 +24,7 @@ -export([newformat/3]). %% These are used by the inets test-suite --export([delay/1]). +-export([delay/1, chunk_timeout/3]). print(String) -> @@ -142,3 +142,11 @@ i(F) -> i(F,[]). i(F,A) -> io:format(F ++ "~n",A). sleep(T) -> receive after T -> ok end. + +%% ------------------------------------------------------ + +chunk_timeout(SessionID, _, StrInt) -> + mod_esi:deliver(SessionID, "Tranfer-Encoding:chunked/html\r\n\r\n"), + mod_esi:deliver(SessionID, top("Test chunk encoding timeout")), + timer:sleep(20000), + mod_esi:deliver(SessionID, footer()). diff --git a/lib/inets/src/http_server/httpd_request_handler.erl b/lib/inets/src/http_server/httpd_request_handler.erl index 143d599edb..134576059d 100644 --- a/lib/inets/src/http_server/httpd_request_handler.erl +++ b/lib/inets/src/http_server/httpd_request_handler.erl @@ -630,21 +630,10 @@ decrease(N) when is_integer(N) -> decrease(N) -> N. -error_log(ReasonString, Info) -> +error_log(ReasonString, #mod{config_db = ConfigDB}) -> Error = lists:flatten( io_lib:format("Error reading request: ~s", [ReasonString])), - error_log(mod_log, Info, Error), - error_log(mod_disk_log, Info, Error). - -error_log(Mod, #mod{config_db = ConfigDB} = Info, String) -> - Modules = httpd_util:lookup(ConfigDB, modules, - [mod_get, mod_head, mod_log]), - case lists:member(Mod, Modules) of - true -> - Mod:error_log(Info, String); - _ -> - ok - end. + httpd_util:error_log(ConfigDB, Error). %%-------------------------------------------------------------------- diff --git a/lib/inets/src/http_server/httpd_response.erl b/lib/inets/src/http_server/httpd_response.erl index 71243f525a..c0b5f09faf 100644 --- a/lib/inets/src/http_server/httpd_response.erl +++ b/lib/inets/src/http_server/httpd_response.erl @@ -20,8 +20,8 @@ %% -module(httpd_response). -export([generate_and_send_response/1, send_status/3, send_header/3, - send_body/3, send_chunk/3, send_final_chunk/2, split_header/2, - is_disable_chunked_send/1, cache_headers/2]). + send_body/3, send_chunk/3, send_final_chunk/2, send_final_chunk/3, + split_header/2, is_disable_chunked_send/1, cache_headers/2]). -export([map_status_code/2]). -include_lib("inets/src/inets_app/inets_internal.hrl"). @@ -89,8 +89,7 @@ traverse_modules(ModData,[Module|Rest]) -> "~n Error: ~p" "~n Stack trace: ~p", [Module, T, E, ?STACK()])), - report_error(mod_log, ModData#mod.config_db, String), - report_error(mod_disk_log, ModData#mod.config_db, String), + httpd_util:error_log(ModData#mod.config_db, String), send_status(ModData, 500, none), done end. @@ -245,7 +244,6 @@ send_chunk(_, <<>>, _) -> ok; send_chunk(_, [], _) -> ok; - send_chunk(#mod{http_version = "HTTP/1.1", socket_type = Type, socket = Sock}, Response0, false) -> Response = http_chunk:encode(Response0), @@ -254,10 +252,13 @@ send_chunk(#mod{http_version = "HTTP/1.1", send_chunk(#mod{socket_type = Type, socket = Sock} = _ModData, Response, _) -> httpd_socket:deliver(Type, Sock, Response). +send_final_chunk(Mod, IsDisableChunkedSend) -> + send_final_chunk(Mod, [], IsDisableChunkedSend). + send_final_chunk(#mod{http_version = "HTTP/1.1", - socket_type = Type, socket = Sock}, false) -> - httpd_socket:deliver(Type, Sock, http_chunk:encode_last()); -send_final_chunk(#mod{socket_type = Type, socket = Sock}, _) -> + socket_type = Type, socket = Sock}, Trailers, false) -> + httpd_socket:deliver(Type, Sock, http_chunk:encode_last(Trailers)); +send_final_chunk(#mod{socket_type = Type, socket = Sock}, _, _) -> httpd_socket:close(Type, Sock). is_disable_chunked_send(Db) -> @@ -397,16 +398,6 @@ send_response_old(#mod{socket_type = Type, content_length(Body)-> integer_to_list(httpd_util:flatlength(Body)). -report_error(Mod, ConfigDB, Error) -> - Modules = httpd_util:lookup(ConfigDB, modules, - [mod_get, mod_head, mod_log]), - case lists:member(Mod, Modules) of - true -> - Mod:report_error(ConfigDB, Error); - _ -> - ok - end. - handle_headers([], NewHeaders) -> {ok, NewHeaders}; diff --git a/lib/inets/src/http_server/httpd_util.erl b/lib/inets/src/http_server/httpd_util.erl index 0387d71911..ab43f0b378 100644 --- a/lib/inets/src/http_server/httpd_util.erl +++ b/lib/inets/src/http_server/httpd_util.erl @@ -31,7 +31,7 @@ convert_netscapecookie_date/1, enable_debug/1, valid_options/3, modules_validate/1, module_validate/1, dir_validate/2, file_validate/2, mime_type_validate/1, - mime_types_validate/1, custom_date/0]). + mime_types_validate/1, custom_date/0, error_log/2]). -export([encode_hex/1, decode_hex/1]). -include_lib("kernel/include/file.hrl"). @@ -776,3 +776,17 @@ do_enable_debug([{Level,Modules}|Rest]) ok end, do_enable_debug(Rest). + +error_log(ConfigDb, Error) -> + error_log(mod_log, ConfigDb, Error), + error_log(mod_disk_log, ConfigDb, Error). + +error_log(Mod, ConfigDB, Error) -> + Modules = httpd_util:lookup(ConfigDB, modules, + [mod_get, mod_head, mod_log]), + case lists:member(Mod, Modules) of + true -> + Mod:report_error(ConfigDB, Error); + _ -> + ok + end. diff --git a/lib/inets/src/http_server/mod_esi.erl b/lib/inets/src/http_server/mod_esi.erl index b9a0797977..1923411449 100644 --- a/lib/inets/src/http_server/mod_esi.erl +++ b/lib/inets/src/http_server/mod_esi.erl @@ -376,7 +376,6 @@ erl_scheme_webpage_chunk(Mod, Func, Env, Input, ModData) -> end), Response = deliver_webpage_chunk(ModData, Pid), - process_flag(trap_exit,false), Response. @@ -418,7 +417,6 @@ deliver_webpage_chunk(#mod{config_db = Db} = ModData, Pid, Timeout) -> ?hdrv("deliver_webpage_chunk - timeout", []), send_headers(ModData, 504, [{"connection", "close"}]), httpd_socket:close(ModData#mod.socket_type, ModData#mod.socket), - process_flag(trap_exit,false), {proceed,[{response, {already_sent, 200, 0}} | ModData#mod.data]} end. @@ -446,7 +444,6 @@ send_headers(ModData, StatusCode, HTTPHeaders) -> ExtraHeaders ++ HTTPHeaders). handle_body(_, #mod{method = "HEAD"} = ModData, _, _, Size, _) -> - process_flag(trap_exit,false), {proceed, [{response, {already_sent, 200, Size}} | ModData#mod.data]}; handle_body(Pid, ModData, Body, Timeout, Size, IsDisableChunkedSend) -> @@ -454,34 +451,54 @@ handle_body(Pid, ModData, Body, Timeout, Size, IsDisableChunkedSend) -> httpd_response:send_chunk(ModData, Body, IsDisableChunkedSend), receive {esi_data, Data} when is_binary(Data) -> - ?hdrt("handle_body - received binary data (esi)", []), handle_body(Pid, ModData, Data, Timeout, Size + byte_size(Data), IsDisableChunkedSend); {esi_data, Data} -> - ?hdrt("handle_body - received data (esi)", []), handle_body(Pid, ModData, Data, Timeout, Size + length(Data), IsDisableChunkedSend); {ok, Data} -> - ?hdrt("handle_body - received data (ok)", []), handle_body(Pid, ModData, Data, Timeout, Size + length(Data), IsDisableChunkedSend); {'EXIT', Pid, normal} when is_pid(Pid) -> - ?hdrt("handle_body - exit:normal", []), httpd_response:send_final_chunk(ModData, IsDisableChunkedSend), {proceed, [{response, {already_sent, 200, Size}} | ModData#mod.data]}; {'EXIT', Pid, Reason} when is_pid(Pid) -> - ?hdrv("handle_body - exit", [{reason, Reason}]), - httpd_response:send_final_chunk(ModData, IsDisableChunkedSend), - exit({mod_esi_linked_process_died, Pid, Reason}) - + Error = lists:flatten(io_lib:format("mod_esi process failed with reason ~p", [Reason])), + httpd_util:error_log(ModData#mod.config_db, Error), + httpd_response:send_final_chunk(ModData, + [{"Warning", "199 inets server - body maybe incomplete, " + "internal server error"}], + IsDisableChunkedSend), + done after Timeout -> - ?hdrv("handle_body - timeout", []), - process_flag(trap_exit,false), - httpd_response:send_final_chunk(ModData, IsDisableChunkedSend), - exit({mod_esi_linked_process_timeout, Pid}) + kill_esi_delivery_process(Pid), + httpd_response:send_final_chunk(ModData, [{"Warning", "199 inets server - " + "body maybe incomplete, timed out"}], + IsDisableChunkedSend), + done end. +kill_esi_delivery_process(Pid) -> + exit(Pid, kill), + receive + {'EXIT', Pid, killed} -> + %% Clean message queue + receive + {esi_data, _} -> + ok + after 0 -> + ok + end, + receive + {ok, _} -> + ok + after 0 -> + ok + end + end. + + erl_script_timeout(Db) -> httpd_util:lookup(Db, erl_script_timeout, ?DEFAULT_ERL_TIMEOUT). diff --git a/lib/inets/test/http_format_SUITE.erl b/lib/inets/test/http_format_SUITE.erl index a927adc75e..e977bd1b9b 100644 --- a/lib/inets/test/http_format_SUITE.erl +++ b/lib/inets/test/http_format_SUITE.erl @@ -38,6 +38,7 @@ groups() -> [chunk_decode, chunk_encode, chunk_extensions_otp_6005, chunk_decode_otp_6264, chunk_decode_empty_chunk_otp_6511, + chunk_whitespace_suffix, chunk_decode_trailer, chunk_max_headersize, chunk_max_bodysize, chunk_not_hex]}]. init_per_suite(Config) -> @@ -157,6 +158,21 @@ chunk_decode_empty_chunk_otp_6511(Config) when is_list(Config) -> ?HTTP_MAX_BODY_SIZE, ?HTTP_MAX_HEADER_SIZE). %%------------------------------------------------------------------------- +chunk_whitespace_suffix() -> + [{doc, "Test whitespace after chunked length header"}]. +chunk_whitespace_suffix(Config) when is_list(Config) -> + ChunkedBody = "1a ; ignore-stuff-here" ++ ?CRLF ++ + "abcdefghijklmnopqrstuvwxyz" ++ ?CRLF ++ "10 " ++ ?CRLF + ++ "1234567890abcdef" ++ ?CRLF ++ "0 " ++ ?CRLF + ++ "some-footer:some-value" ++ ?CRLF + ++ "another-footer:another-value" ++ ?CRLF ++ ?CRLF, + {ok, {["content-length:42", "another-footer:another-value", + "some-footer:some-value", ""], + <<"abcdefghijklmnopqrstuvwxyz1234567890abcdef">>}} = + http_chunk:decode(list_to_binary(ChunkedBody), + ?HTTP_MAX_BODY_SIZE, ?HTTP_MAX_HEADER_SIZE). + +%%------------------------------------------------------------------------- chunk_decode_trailer() -> [{doc,"Make sure trailers are handled correctly. Trailers should" "become new headers"}]. diff --git a/lib/inets/test/httpc_SUITE.erl b/lib/inets/test/httpc_SUITE.erl index 989563cdbc..c6c59ab1af 100644 --- a/lib/inets/test/httpc_SUITE.erl +++ b/lib/inets/test/httpc_SUITE.erl @@ -106,6 +106,7 @@ only_simulated() -> bad_response, internal_server_error, invalid_http, + invalid_chunk_size, headers_dummy, headers_with_obs_fold, empty_response_header, @@ -765,6 +766,22 @@ invalid_http(Config) when is_list(Config) -> ct:print("Parse error: ~p ~n", [Reason]). %%------------------------------------------------------------------------- + +invalid_chunk_size(doc) -> + ["Test parse error of HTTP chunk size"]; +invalid_chunk_size(suite) -> + []; +invalid_chunk_size(Config) when is_list(Config) -> + + URL = url(group_name(Config), "/invalid_chunk_size.html", Config), + + {error, {chunk_size, _} = Reason} = + httpc:request(get, {URL, []}, [], []), + + ct:print("Parse error: ~p ~n", [Reason]). + +%%------------------------------------------------------------------------- + emulate_lower_versions(doc) -> [{doc, "Perform request as 0.9 and 1.0 clients."}]; emulate_lower_versions(Config) when is_list(Config) -> @@ -1876,6 +1893,10 @@ handle_uri(_,"/invalid_http.html",_,_,_,_) -> "HTTP/1.1 301\r\nDate:Sun, 09 Dec 2007 13:04:18 GMT\r\n" ++ "Transfer-Encoding:chunked\r\n\r\n"; +handle_uri(_,"/invalid_chunk_size.html",_,_,_,_) -> + "HTTP/1.1 200 ok\r\n" ++ + "Transfer-Encoding:chunked\r\n\r\nåäö\r\n"; + handle_uri(_,"/missing_reason_phrase.html",_,_,_,_) -> "HTTP/1.1 200\r\n" ++ "Content-Length: 32\r\n\r\n" diff --git a/lib/inets/test/httpd_1_1.erl b/lib/inets/test/httpd_1_1.erl index dd9d21bbfc..db6def9d17 100644 --- a/lib/inets/test/httpd_1_1.erl +++ b/lib/inets/test/httpd_1_1.erl @@ -24,7 +24,7 @@ -include_lib("kernel/include/file.hrl"). -export([host/4, chunked/4, expect/4, range/4, if_test/5, trace/4, - head/4, mod_cgi_chunked_encoding_test/5]). + head/4, mod_cgi_chunked_encoding_test/5, mod_esi_chunk_timeout/4]). %% -define(all_keys_lower_case,true). -ifndef(all_keys_lower_case). @@ -274,6 +274,15 @@ mod_cgi_chunked_encoding_test(Type, Port, Host, Node, [Request| Rest])-> [{statuscode, 200}]), mod_cgi_chunked_encoding_test(Type, Port, Host, Node, Rest). + +mod_esi_chunk_timeout(Type, Port, Host, Node) -> + ok = httpd_test_lib:verify_request(Type, Host, Port, Node, + "GET /cgi-bin/erl/httpd_example/chunk_timeout?input=20000 HTTP/1.1\r\n" + "Host:"++ Host ++"\r\n" + "\r\n", + [{statuscode, 200}, + {header, "warning"}]). + %%-------------------------------------------------------------------- %% Internal functions %%-------------------------------------------------------------------- diff --git a/lib/inets/test/httpd_SUITE.erl b/lib/inets/test/httpd_SUITE.erl index 9bd6f3636c..1d8a603981 100644 --- a/lib/inets/test/httpd_SUITE.erl +++ b/lib/inets/test/httpd_SUITE.erl @@ -117,7 +117,7 @@ groups() -> {htaccess, [], [htaccess_1_1, htaccess_1_0, htaccess_0_9]}, {security, [], [security_1_1, security_1_0]}, %% Skip 0.9 as causes timing issus in test code {http_1_1, [], [host, chunked, expect, cgi, cgi_chunked_encoding_test, - trace, range, if_modified_since] ++ http_head() ++ http_get() ++ load()}, + trace, range, if_modified_since, mod_esi_chunk_timeout] ++ http_head() ++ http_get() ++ load()}, {http_1_0, [], [host, cgi, trace] ++ http_head() ++ http_get() ++ load()}, {http_0_9, [], http_head() ++ http_get() ++ load()} ]. @@ -757,6 +757,13 @@ esi(Config) when is_list(Config) -> Config, [{statuscode, 200}, {no_header, "cache-control"}]). %%------------------------------------------------------------------------- +mod_esi_chunk_timeout(Config) when is_list(Config) -> + ok = httpd_1_1:mod_esi_chunk_timeout(?config(type, Config), + ?config(port, Config), + ?config(host, Config), + ?config(node, Config)). + +%%------------------------------------------------------------------------- cgi() -> [{doc, "Test mod_cgi"}]. diff --git a/lib/inets/test/httpd_SUITE_data/Makefile.src b/lib/inets/test/httpd_SUITE_data/Makefile.src index b0fdb43d8d..cea40dd8cb 100644 --- a/lib/inets/test/httpd_SUITE_data/Makefile.src +++ b/lib/inets/test/httpd_SUITE_data/Makefile.src @@ -10,5 +10,10 @@ all: $(PROGS) cgi_echo@exe@: cgi_echo@obj@ $(LD) $(CROSSLDFLAGS) -o cgi_echo cgi_echo@obj@ @LIBS@ +@IFEQ@ (@CC@, cl -nologo) +cgi_echo@obj@: cgi_echo.c + $(CC) /c /Focgi_echo@obj@ $(CFLAGS) cgi_echo.c +@ELSE@ cgi_echo@obj@: cgi_echo.c $(CC) -c -o cgi_echo@obj@ $(CFLAGS) cgi_echo.c +@ENDIF@ diff --git a/lib/inets/test/httpd_test_lib.erl b/lib/inets/test/httpd_test_lib.erl index a5b836f651..c58966ce10 100644 --- a/lib/inets/test/httpd_test_lib.erl +++ b/lib/inets/test/httpd_test_lib.erl @@ -235,11 +235,17 @@ validate(RequestStr, #state{status_line = {Version, StatusCode, _}, _ -> ok end, - do_validate(http_response:header_list(Headers), Options, N, P), - check_body(RequestStr, StatusCode, - Headers#http_response_h.'content-type', - list_to_integer(Headers#http_response_h.'content-length'), - Body). + HList = http_response:header_list(Headers), + do_validate(HList, Options, N, P), + case lists:keysearch("warning", 1, HList) of + {value, _} -> + ok; + _ -> + check_body(RequestStr, StatusCode, + Headers#http_response_h.'content-type', + list_to_integer(Headers#http_response_h.'content-length'), + Body) + end. %-------------------------------------------------------------------- %% Internal functions diff --git a/lib/kernel/doc/src/notes.xml b/lib/kernel/doc/src/notes.xml index 268a8404f1..d02c3e8ad2 100644 --- a/lib/kernel/doc/src/notes.xml +++ b/lib/kernel/doc/src/notes.xml @@ -185,6 +185,22 @@ </section> +<section><title>Kernel 3.2.0.1</title> + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>The 'raw' socket option could not be used multiple times + in one call to any e.g gen_tcp function because only one + of the occurrences were used. This bug has been fixed, + and also a small bug concerning propagating error codes + from within inet:setopts/2.</p> + <p>Own Id: OTP-11482 Aux Id: seq12872 </p> + </item> + </list> + </section> + </section> + + <section><title>Kernel 3.2</title> <section><title>Fixed Bugs and Malfunctions</title> diff --git a/lib/kernel/src/file_io_server.erl b/lib/kernel/src/file_io_server.erl index bf8b9e2747..deb7b315b1 100644 --- a/lib/kernel/src/file_io_server.erl +++ b/lib/kernel/src/file_io_server.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2000-2013. All Rights Reserved. +%% Copyright Ericsson AB 2000-2015. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -206,8 +206,8 @@ io_reply(From, ReplyAs, Reply) -> file_request({advise,Offset,Length,Advise}, #state{handle=Handle}=State) -> case ?PRIM_FILE:advise(Handle, Offset, Length, Advise) of - {error,_}=Reply -> - {stop,normal,Reply,State}; + {error,Reason}=Reply -> + {stop,Reason,Reply,State}; Reply -> {reply,Reply,State} end; @@ -215,62 +215,91 @@ file_request({allocate, Offset, Length}, #state{handle = Handle} = State) -> Reply = ?PRIM_FILE:allocate(Handle, Offset, Length), {reply, Reply, State}; +file_request({pread,At,Sz}, State) + when At =:= cur; + At =:= {cur,0} -> + case get_chars(Sz, latin1, State) of + {reply,Reply,NewState} + when is_list(Reply); + is_binary(Reply) -> + {reply,{ok,Reply},NewState}; + Other -> + Other + end; file_request({pread,At,Sz}, - #state{handle=Handle,buf=Buf,read_mode=ReadMode}=State) -> + #state{handle=Handle,buf=Buf}=State) -> case position(Handle, At, Buf) of - {ok,_Offs} -> - case ?PRIM_FILE:read(Handle, Sz) of - {ok,Bin} when ReadMode =:= list -> - std_reply({ok,binary_to_list(Bin)}, State); - Reply -> - std_reply(Reply, State) - end; - Reply -> - std_reply(Reply, State) + {error,_} = Reply -> + {error,Reply,State}; + _ -> + case get_chars(Sz, latin1, State#state{buf= <<>>}) of + {reply,Reply,NewState} + when is_list(Reply); + is_binary(Reply) -> + {reply,{ok,Reply},NewState}; + Other -> + Other + end end; +file_request({pwrite,At,Data}, + #state{buf= <<>>}=State) + when At =:= cur; + At =:= {cur,0} -> + put_chars(Data, latin1, State); file_request({pwrite,At,Data}, #state{handle=Handle,buf=Buf}=State) -> case position(Handle, At, Buf) of - {ok,_Offs} -> - std_reply(?PRIM_FILE:write(Handle, Data), State); - Reply -> - std_reply(Reply, State) + {error,_} = Reply -> + {error,Reply,State}; + _ -> + put_chars(Data, latin1, State) end; file_request(datasync, #state{handle=Handle}=State) -> case ?PRIM_FILE:datasync(Handle) of - {error,_}=Reply -> - {stop,normal,Reply,State}; + {error,Reason}=Reply -> + {stop,Reason,Reply,State}; Reply -> {reply,Reply,State} end; file_request(sync, #state{handle=Handle}=State) -> case ?PRIM_FILE:sync(Handle) of - {error,_}=Reply -> - {stop,normal,Reply,State}; + {error,Reason}=Reply -> + {stop,Reason,Reply,State}; Reply -> {reply,Reply,State} end; file_request(close, #state{handle=Handle}=State) -> - {stop,normal,?PRIM_FILE:close(Handle),State#state{buf= <<>>}}; + case ?PRIM_FILE:close(Handle) of + {error,Reason}=Reply -> + {stop,Reason,Reply,State#state{buf= <<>>}}; + Reply -> + {stop,normal,Reply,State#state{buf= <<>>}} + end; file_request({position,At}, #state{handle=Handle,buf=Buf}=State) -> - std_reply(position(Handle, At, Buf), State); + case position(Handle, At, Buf) of + {error,_} = Reply -> + {error,Reply,State}; + Reply -> + std_reply(Reply, State) + end; file_request(truncate, #state{handle=Handle}=State) -> case ?PRIM_FILE:truncate(Handle) of - {error,_Reason}=Reply -> - {stop,normal,Reply,State#state{buf= <<>>}}; + {error,Reason}=Reply -> + {stop,Reason,Reply,State#state{buf= <<>>}}; Reply -> - {reply,Reply,State} + std_reply(Reply, State) end; file_request(Unknown, #state{}=State) -> Reason = {request, Unknown}, {error,{error,Reason},State}. +%% Standard reply and clear buffer std_reply({error,_}=Reply, State) -> {error,Reply,State#state{buf= <<>>}}; std_reply(Reply, State) -> @@ -286,8 +315,8 @@ io_request({put_chars, Enc, Chars}, io_request({put_chars, Enc, Chars}, #state{handle=Handle,buf=Buf}=State) -> case position(Handle, cur, Buf) of - {error,_}=Reply -> - {stop,normal,Reply,State#state{buf= <<>>}}; + {error,Reason}=Reply -> + {stop,Reason,Reply,State}; _ -> put_chars(Chars, Enc, State#state{buf= <<>>}) end; @@ -368,23 +397,27 @@ io_request_loop([Request|Tail], %% I/O request put_chars %% put_chars(Chars, latin1, #state{handle=Handle, unic=latin1}=State) -> + NewState = State#state{buf = <<>>}, case ?PRIM_FILE:write(Handle, Chars) of - {error,_}=Reply -> - {stop,normal,Reply,State}; + {error,Reason}=Reply -> + {stop,Reason,Reply,NewState}; Reply -> - {reply,Reply,State} + {reply,Reply,NewState} end; put_chars(Chars, InEncoding, #state{handle=Handle, unic=OutEncoding}=State) -> + NewState = State#state{buf = <<>>}, case unicode:characters_to_binary(Chars,InEncoding,OutEncoding) of Bin when is_binary(Bin) -> case ?PRIM_FILE:write(Handle, Bin) of - {error,_}=Reply -> - {stop,normal,Reply,State}; + {error,Reason}=Reply -> + {stop,Reason,Reply,NewState}; Reply -> - {reply,Reply,State} + {reply,Reply,NewState} end; {error,_,_} -> - {stop,normal,{error,{no_translation, InEncoding, OutEncoding}},State} + {stop,no_translation, + {error,{no_translation, InEncoding, OutEncoding}}, + NewState} end. get_line(S, {<<>>, Cont}, OutEnc, @@ -884,11 +917,14 @@ cbv({utf32,little},_) -> %% Compensates ?PRIM_FILE:position/2 for the number of bytes %% we have buffered - -position(Handle, cur, Buf) -> - position(Handle, {cur, 0}, Buf); -position(Handle, {cur, Offs}, Buf) when is_binary(Buf) -> - ?PRIM_FILE:position(Handle, {cur, Offs-byte_size(Buf)}); -position(Handle, At, _Buf) -> - ?PRIM_FILE:position(Handle, At). - +position(Handle, At, Buf) -> + ?PRIM_FILE:position( + Handle, + case At of + cur -> + {cur, -byte_size(Buf)}; + {cur, Offs} -> + {cur, Offs-byte_size(Buf)}; + _ -> + At + end). diff --git a/lib/kernel/src/inet.erl b/lib/kernel/src/inet.erl index 855c6377a3..b573112445 100644 --- a/lib/kernel/src/inet.erl +++ b/lib/kernel/src/inet.erl @@ -692,6 +692,7 @@ connect_options(Opts, Family) -> case con_opt(Opts, BaseOpts, connect_options()) of {ok, R} -> {ok, R#connect_opts { + opts = lists:reverse(R#connect_opts.opts), ifaddr = translate_ip(R#connect_opts.ifaddr, Family) }}; Error -> Error @@ -762,6 +763,7 @@ listen_options(Opts, Family) -> case list_opt(Opts, BaseOpts, listen_options()) of {ok, R} -> {ok, R#listen_opts { + opts = lists:reverse(R#listen_opts.opts), ifaddr = translate_ip(R#listen_opts.ifaddr, Family) }}; Error -> Error @@ -820,6 +822,7 @@ udp_options(Opts, Family) -> case udp_opt(Opts, #udp_opts { }, udp_options()) of {ok, R} -> {ok, R#udp_opts { + opts = lists:reverse(R#udp_opts.opts), ifaddr = translate_ip(R#udp_opts.ifaddr, Family) }}; Error -> Error @@ -893,9 +896,12 @@ sctp_options() -> sctp_options(Opts, Mod) -> case sctp_opt(Opts, Mod, #sctp_opts{}, sctp_options()) of {ok,#sctp_opts{ifaddr=undefined}=SO} -> - {ok,SO#sctp_opts{ifaddr=Mod:translate_ip(?SCTP_DEF_IFADDR)}}; - {ok,_}=OK -> - OK; + {ok, + SO#sctp_opts{ + opts=lists:reverse(SO#sctp_opts.opts), + ifaddr=Mod:translate_ip(?SCTP_DEF_IFADDR)}}; + {ok,SO} -> + {ok,SO#sctp_opts{opts=lists:reverse(SO#sctp_opts.opts)}}; Error -> Error end. @@ -967,6 +973,8 @@ add_opt(Name, Val, Opts, As) -> case lists:member(Name, As) of true -> case prim_inet:is_sockopt_val(Name, Val) of + true when Name =:= raw -> + {ok, [{Name,Val} | Opts]}; true -> Opts1 = lists:keydelete(Name, 1, Opts), {ok, [{Name,Val} | Opts1]}; diff --git a/lib/kernel/test/file_SUITE.erl b/lib/kernel/test/file_SUITE.erl index 8856be31c2..09d9a45197 100644 --- a/lib/kernel/test/file_SUITE.erl +++ b/lib/kernel/test/file_SUITE.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 1996-2013. All Rights Reserved. +%% Copyright Ericsson AB 1996-2015. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -48,7 +48,7 @@ -export([cur_dir_0/1, cur_dir_1/1, make_del_dir/1, list_dir/1,list_dir_error/1, untranslatable_names/1, untranslatable_names_error/1, - pos1/1, pos2/1]). + pos1/1, pos2/1, pos3/1]). -export([close/1, consult1/1, path_consult/1, delete/1]). -export([ eval1/1, path_eval/1, script1/1, path_script/1, open1/1, @@ -80,6 +80,7 @@ -export([interleaved_read_write/1]). +-export([unicode/1]). -export([altname/1]). -export([large_file/1, large_write/1]). @@ -114,7 +115,7 @@ suite() -> [{ct_hooks,[ts_install_cth]}]. all() -> - [altname, read_write_file, {group, dirs}, + [unicode, altname, read_write_file, {group, dirs}, {group, files}, delete, rename, names, {group, errors}, {group, compression}, {group, links}, copy, delayed_write, read_ahead, segment_read, segment_write, @@ -136,7 +137,7 @@ groups() -> [open1, old_modes, new_modes, path_open, close, access, read_write, pread_write, append, open_errors, exclusive]}, - {pos, [], [pos1, pos2]}, + {pos, [], [pos1, pos2, pos3]}, {file_info, [], [file_info_basic_file, file_info_basic_directory, file_info_bad, file_info_times, file_write_file_info]}, @@ -1370,6 +1371,27 @@ pos2(Config) when is_list(Config) -> ?line test_server:timetrap_cancel(Dog), ok. +pos3(suite) -> []; +pos3(doc) -> ["When it does not use raw mode, file:position had a bug."]; +pos3(Config) when is_list(Config) -> + ?line Dog = test_server:timetrap(test_server:seconds(5)), + ?line RootDir = ?config(data_dir, Config), + ?line Name = filename:join(RootDir, "realmen.html.gz"), + + ?line {ok, Fd} = ?FILE_MODULE:open(Name, [read, binary]), + ?line {ok, _} = ?FILE_MODULE:read(Fd, 5), + ?line {error, einval} = ?FILE_MODULE:position(Fd, {bof, -1}), + + %% Here ok had returned =( + ?line {error, einval} = ?FILE_MODULE:position(Fd, {cur, -10}), + %% That test is actually questionable since file:position/2 + %% is documented to leave the file position undefined after + %% it has returned an error. But on Posix systems the position + %% is guaranteed to be unchanged after an error return. On e.g + %% Windows there is nothing stated about this in the documentation. + + ?line test_server:timetrap_cancel(Dog), + ok. file_info_basic_file(suite) -> []; file_info_basic_file(doc) -> []; @@ -2761,6 +2783,40 @@ compress_async_crash_loop(N, Path, ExpectedData) -> %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +unicode(Config) when is_list(Config) -> + Dir = ?config(priv_dir, Config), + Name = filename:join(Dir, "data-utf8.txt"), + Txt = lists:seq(128, 255), + D = unicode:characters_to_binary(Txt, latin1, latin1), + {ok,Fd1} = + ?FILE_MODULE:open(Name, [write,read,binary,{encoding,unicode}]), + ok = ?FILE_MODULE:truncate(Fd1), + ok = ?FILE_MODULE:write(Fd1, Txt), + {ok,0} = ?FILE_MODULE:position(Fd1, bof), + {ok,D} = ?FILE_MODULE:read(Fd1, 129), + {ok,0} = ?FILE_MODULE:position(Fd1, bof), + {ok,D1} = ?FILE_MODULE:read(Fd1, 64), + {ok,Pos} = ?FILE_MODULE:position(Fd1, cur), + {ok,D2} = ?FILE_MODULE:pread(Fd1, {cur,0}, 65), + D = <<D1/binary, D2/binary>>, + {ok,D1} = ?FILE_MODULE:pread(Fd1, bof, 64), + {ok,Pos} = ?FILE_MODULE:position(Fd1, Pos), + {ok,D2} = ?FILE_MODULE:read(Fd1, 64), + ok = ?FILE_MODULE:close(Fd1), + %% + RawD = unicode:characters_to_binary(Txt, latin1, unicode), + {ok,RawD} = ?FILE_MODULE:read_file(Name), + %% + {ok,Fd2} = ?FILE_MODULE:open(Name, [read,{encoding,unicode}]), + {ok,Txt} = ?FILE_MODULE:read(Fd2, 129), + {Txt1,Txt2} = lists:split(64, Txt), + {ok,Txt2} = ?FILE_MODULE:pread(Fd2, Pos, 65), + {ok,0} = ?FILE_MODULE:position(Fd2, bof), + {ok,Txt1} = ?FILE_MODULE:read(Fd2, 64), + ok = ?FILE_MODULE:close(Fd2). + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + altname(doc) -> "Test the file:altname/1 function"; altname(suite) -> diff --git a/lib/kernel/test/inet_sockopt_SUITE.erl b/lib/kernel/test/inet_sockopt_SUITE.erl index 1262f36fae..cb522c8abe 100644 --- a/lib/kernel/test/inet_sockopt_SUITE.erl +++ b/lib/kernel/test/inet_sockopt_SUITE.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2007-2013. All Rights Reserved. +%% Copyright Ericsson AB 2007-2015. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -52,6 +52,7 @@ -export([all/0, suite/0,groups/0,init_per_suite/1, end_per_suite/1, init_per_group/2,end_per_group/2, simple/1, loop_all/1, simple_raw/1, simple_raw_getbin/1, + multiple_raw/1, multiple_raw_getbin/1, doc_examples_raw/1,doc_examples_raw_getbin/1, large_raw/1,large_raw_getbin/1,combined/1,combined_getbin/1, ipv6_v6only_udp/1, ipv6_v6only_tcp/1, ipv6_v6only_sctp/1, @@ -65,6 +66,7 @@ suite() -> [{ct_hooks,[ts_install_cth]}]. all() -> [simple, loop_all, simple_raw, simple_raw_getbin, + multiple_raw, multiple_raw_getbin, doc_examples_raw, doc_examples_raw_getbin, large_raw, large_raw_getbin, combined, combined_getbin, ipv6_v6only_udp, ipv6_v6only_tcp, ipv6_v6only_sctp, @@ -185,6 +187,84 @@ nintbin2int(<<Int:16/native>>) -> Int; nintbin2int(<<Int:8/native>>) -> Int; nintbin2int(<<>>) -> 0. + + +multiple_raw(suite) -> []; +multiple_raw(doc) -> "Test setopt/getopt of multiple raw options."; +multiple_raw(Config) when is_list(Config) -> + do_multiple_raw(Config,false). +multiple_raw_getbin(suite) -> []; +multiple_raw_getbin(doc) -> "Test setopt/getopt of multiple raw options, " + "with binaries in getopt."; +multiple_raw_getbin(Config) when is_list(Config) -> + do_multiple_raw(Config,true). + +do_multiple_raw(Config, Binary) -> + Port = start_helper(Config), + SolSocket = ask_helper(Port, ?C_GET_SOL_SOCKET), + SoKeepalive = ask_helper(Port, ?C_GET_SO_KEEPALIVE), + SoKeepaliveTrue = {raw,SolSocket,SoKeepalive,<<1:32/native>>}, + SoKeepaliveFalse = {raw,SolSocket,SoKeepalive,<<0:32/native>>}, + SoReuseaddr = ask_helper(Port, ?C_GET_SO_REUSEADDR), + SoReuseaddrTrue = {raw,SolSocket,SoReuseaddr,<<1:32/native>>}, + SoReuseaddrFalse = {raw,SolSocket,SoReuseaddr,<<0:32/native>>}, + {S1,S2} = + create_socketpair( + [SoReuseaddrFalse,SoKeepaliveTrue], + [SoKeepaliveFalse,SoReuseaddrTrue]), + {ok,[{reuseaddr,false},{keepalive,true}]} = + inet:getopts(S1, [reuseaddr,keepalive]), + {ok, + [{raw,SolSocket,SoReuseaddr,S1R1}, + {raw,SolSocket,SoKeepalive,S1K1}]} = + inet:getopts( + S1, + [{raw,SolSocket,SoReuseaddr,binarify(4, Binary)}, + {raw,SolSocket,SoKeepalive,binarify(4, Binary)}]), + true = nintbin2int(S1R1) =:= 0, + true = nintbin2int(S1K1) =/= 0, + {ok,[{keepalive,false},{reuseaddr,true}]} = + inet:getopts(S2, [keepalive,reuseaddr]), + {ok, + [{raw,SolSocket,SoKeepalive,S2K1}, + {raw,SolSocket,SoReuseaddr,S2R1}]} = + inet:getopts( + S2, + [{raw,SolSocket,SoKeepalive,binarify(4, Binary)}, + {raw,SolSocket,SoReuseaddr,binarify(4, Binary)}]), + true = nintbin2int(S2K1) =:= 0, + true = nintbin2int(S2R1) =/= 0, + %% + ok = inet:setopts( + S1, [SoReuseaddrTrue,SoKeepaliveFalse]), + ok = inet:setopts( + S2, [SoKeepaliveTrue,SoReuseaddrFalse]), + {ok, + [{raw,SolSocket,SoReuseaddr,S1R2}, + {raw,SolSocket,SoKeepalive,S1K2}]} = + inet:getopts( + S1, + [{raw,SolSocket,SoReuseaddr,binarify(4, Binary)}, + {raw,SolSocket,SoKeepalive,binarify(4, Binary)}]), + true = nintbin2int(S1R2) =/= 0, + true = nintbin2int(S1K2) =:= 0, + {ok, + [{raw,SolSocket,SoKeepalive,S2K2}, + {raw,SolSocket,SoReuseaddr,S2R2}]} = + inet:getopts( + S2, + [{raw,SolSocket,SoKeepalive,binarify(4, Binary)}, + {raw,SolSocket,SoReuseaddr,binarify(4, Binary)}]), + true = nintbin2int(S2K2) =/= 0, + true = nintbin2int(S2R2) =:= 0, + %% + gen_tcp:close(S1), + gen_tcp:close(S2), + stop_helper(Port), + ok. + + + doc_examples_raw(suite) -> []; doc_examples_raw(doc) -> "Test that the example code from the documentation " "works"; diff --git a/lib/snmp/doc/src/snmp_agent_netif.xml b/lib/snmp/doc/src/snmp_agent_netif.xml index 769fd23115..9583f1f521 100644 --- a/lib/snmp/doc/src/snmp_agent_netif.xml +++ b/lib/snmp/doc/src/snmp_agent_netif.xml @@ -76,8 +76,7 @@ <c>{Domain, Addr}</c> tuple where <c>Domain</c> is <c>transportDomainUdpIpv4</c> or <c>transportDomainUdpIpv4</c>, and <c>Addr</c> is an - <c>{<seealso marker="kernel:inet#type-ip_address">IpAddr</seealso>, - IpPort}</c> tuple.</p> + <c>{</c><seealso marker="kernel:inet#type-ip_address"><c>IpAddr</c></seealso><c>,IpPort}</c> tuple.</p> <section> <marker id="outgoing_messages"></marker> diff --git a/lib/snmp/doc/src/snmp_app.xml b/lib/snmp/doc/src/snmp_app.xml index 234a076eda..39aac8e7d7 100644 --- a/lib/snmp/doc/src/snmp_app.xml +++ b/lib/snmp/doc/src/snmp_app.xml @@ -135,16 +135,16 @@ <marker id="agent_opts_and_types"></marker> <p>Agent specific config options and types:</p> <taglist> - <marker id="agent_type"></marker> - <tag><c><![CDATA[agent_type() = master | sub <optional>]]></c></tag> + <tag><marker id="agent_type"></marker> + <c><![CDATA[agent_type() = master | sub <optional>]]></c></tag> <item> <p>If <c>master</c>, one master agent is started. Otherwise, no agents are started. </p> <p>Default is <c>master</c>.</p> </item> - <marker id="agent_disco"></marker> - <tag><c><![CDATA[agent_discovery() = [agent_discovery_opt()] <optional>]]></c></tag> + <tag><marker id="agent_disco"></marker> + <c><![CDATA[agent_discovery() = [agent_discovery_opt()] <optional>]]></c></tag> <item> <p><c>agent_discovery_opt() = {terminating, agent_terminating_discovery_opts()} | @@ -156,8 +156,8 @@ <p>For defaults see the options in <c>agent_discovery_opt()</c>.</p> </item> - <marker id="agent_term_disco_opts"></marker> - <tag><c><![CDATA[agent_terminating_discovery_opts() = [agent_terminating_discovery_opt()] <optional>]]></c></tag> + <tag><marker id="agent_term_disco_opts"></marker> + <c><![CDATA[agent_terminating_discovery_opts() = [agent_terminating_discovery_opt()] <optional>]]></c></tag> <item> <p><c>agent_terminating_discovery_opt() = {enable, boolean()} | @@ -174,8 +174,8 @@ </list> </item> - <marker id="agent_orig_disco_opts"></marker> - <tag><c><![CDATA[agent_originating_discovery_opts() = [agent_originating_discovery_opt()] <optional>]]></c></tag> + <tag><marker id="agent_orig_disco_opts"></marker> + <c><![CDATA[agent_originating_discovery_opts() = [agent_originating_discovery_opt()] <optional>]]></c></tag> <item> <p><c>agent_originating_discovery_opt() = {enable, boolean()}</c></p> @@ -188,38 +188,39 @@ </list> </item> - <marker id="agent_mt"></marker> - <tag><c><![CDATA[multi_threaded() = bool() <optional>]]></c></tag> + <tag><marker id="agent_mt"></marker> + <c><![CDATA[multi_threaded() = bool() <optional>]]></c></tag> <item> <p>If <c>true</c>, the agent is multi-threaded, with one thread for each get request. </p> <p>Default is <c>false</c>.</p> </item> - <marker id="agent_data_dir"></marker> - <tag><c><![CDATA[db_dir() = string() <mandatory>]]></c></tag> + <tag><marker id="agent_data_dir"></marker> + <c><![CDATA[db_dir() = string() <mandatory>]]></c></tag> <item> <p>Defines where the SNMP agent internal db files are stored.</p> </item> - <marker id="agent_gb_max_vbs"></marker> - <tag><c><![CDATA[gb_max_vbs() = pos_integer() | infinity <optional>]]></c></tag> + + <tag><marker id="agent_gb_max_vbs"></marker> + <c><![CDATA[gb_max_vbs() = pos_integer() | infinity <optional>]]></c></tag> <item> <p>Defines the maximum number of varbinds allowed in a Get-BULK response.</p> <p>Default is <c>1000</c>.</p> </item> - <marker id="agent_local_db"></marker> - <tag><c><![CDATA[local_db() = [local_db_opt()] <optional>]]></c></tag> + <tag><marker id="agent_local_db"></marker> + <c><![CDATA[local_db() = [local_db_opt()] <optional>]]></c></tag> <item> <p><c>local_db_opt() = {repair, agent_repair()} | {auto_save, agent_auto_save()} | {verbosity, verbosity()}</c></p> <p>Defines options specific for the SNMP agent local database.</p> <p>For defaults see the options in <c>local_db_opt()</c>.</p> </item> - <marker id="agent_ldb_repair"></marker> - <tag><c><![CDATA[agent_repair() = false | true | force <optional>]]></c></tag> + <tag><marker id="agent_ldb_repair"></marker> + <c><![CDATA[agent_repair() = false | true | force <optional>]]></c></tag> <item> <p>When starting snmpa_local_db it always tries to open an existing database. If <c>false</c>, and some errors occur, a new @@ -229,16 +230,16 @@ <p>Default is <c>true</c>.</p> </item> - <marker id="agent_ldb_auto_save"></marker> - <tag><c><![CDATA[agent_auto_save() = integer() | infinity <optional>]]></c></tag> + <tag><marker id="agent_ldb_auto_save"></marker> + <c><![CDATA[agent_auto_save() = integer() | infinity <optional>]]></c></tag> <item> <p>The auto save interval. The table is flushed to disk whenever not accessed for this amount of time.</p> <p>Default is <c>5000</c>.</p> </item> - <marker id="agent_net_if"></marker> - <tag><c><![CDATA[agent_net_if() = [agent_net_if_opt()] <optional>]]></c></tag> + <tag><marker id="agent_net_if"></marker> + <c><![CDATA[agent_net_if() = [agent_net_if_opt()] <optional>]]></c></tag> <item> <p><c>agent_net_if_opt() = {module, agent_net_if_module()} | {verbosity, verbosity()} | {options, agent_net_if_options()}</c></p> <p>Defines options specific for the SNMP agent network interface @@ -246,8 +247,8 @@ <p>For defaults see the options in <c>agent_net_if_opt()</c>.</p> </item> - <marker id="agent_ni_module"></marker> - <tag><c><![CDATA[agent_net_if_module() = atom() <optional>]]></c></tag> + <tag><marker id="agent_ni_module"></marker> + <c><![CDATA[agent_net_if_module() = atom() <optional>]]></c></tag> <item> <p>Module which handles the network interface part for the SNMP agent. Must implement the @@ -255,8 +256,8 @@ <p>Default is <c>snmpa_net_if</c>.</p> </item> - <marker id="agent_ni_opts"></marker> - <tag><c><![CDATA[agent_net_if_options() = [agent_net_if_option()] <optional>]]></c></tag> + <tag><marker id="agent_ni_opts"></marker> + <c><![CDATA[agent_net_if_options() = [agent_net_if_option()] <optional>]]></c></tag> <item> <p><c>agent_net_if_option() = {bind_to, bind_to()} | {sndbuf, sndbuf()} | @@ -270,15 +271,15 @@ <p>For defaults see the options in <c>agent_net_if_option()</c>.</p> </item> - <marker id="agent_ni_req_limit"></marker> - <tag><c><![CDATA[req_limit() = integer() | infinity <optional>]]></c></tag> + <tag><marker id="agent_ni_req_limit"></marker> + <c><![CDATA[req_limit() = integer() | infinity <optional>]]></c></tag> <item> <p>Max number of simultaneous requests handled by the agent.</p> <p>Default is <c>infinity</c>.</p> </item> - <marker id="agent_ni_filter_opts"></marker> - <tag><c><![CDATA[agent_net_if_filter_options() = [agent_net_if_filter_option()] <optional>]]></c></tag> + <tag><marker id="agent_ni_filter_opts"></marker> + <c><![CDATA[agent_net_if_filter_options() = [agent_net_if_filter_option()] <optional>]]></c></tag> <item> <p><c>agent_net_if_filter_option() = {module, agent_net_if_filter_module()}</c></p> <p>These options are actually specific to the used module. @@ -288,8 +289,8 @@ <c>agent_net_if_filter_option()</c>.</p> </item> - <marker id="agent_ni_filter_module"></marker> - <tag><c><![CDATA[agent_net_if_filter_module() = atom() <optional>]]></c></tag> + <tag><marker id="agent_ni_filter_module"></marker> + <c><![CDATA[agent_net_if_filter_module() = atom() <optional>]]></c></tag> <item> <p>Module which handles the network interface filter part for the SNMP agent. Must implement the @@ -297,8 +298,8 @@ <p>Default is <c>snmpa_net_if_filter</c>.</p> </item> - <marker id="agent_mibs"></marker> - <tag><c><![CDATA[agent_mibs() = [string()] <optional>]]></c></tag> + <tag><marker id="agent_mibs"></marker> + <c><![CDATA[agent_mibs() = [string()] <optional>]]></c></tag> <item> <p>Specifies a list of MIBs (including path) that defines which MIBs are initially loaded into the SNMP master agent. </p> @@ -312,8 +313,8 @@ <p>Default is <c>[]</c>.</p> </item> - <marker id="agent_mib_storage"></marker> - <tag><c><![CDATA[mib_storage() = [mib_storage_opt()] <optional>]]></c></tag> + <tag><marker id="agent_mib_storage"></marker> + <c><![CDATA[mib_storage() = [mib_storage_opt()] <optional>]]></c></tag> <item> <p><c>mib_storage_opt() = {module, mib_storage_module()} | {options, mib_storage_options()}</c></p> <p>This option specifies how basic mib data is stored. @@ -322,8 +323,8 @@ <p>Default is <c>[{module, snmpa_mib_storage_ets}]</c>. </p> </item> - <marker id="agent_mst_module"></marker> - <tag><c><![CDATA[mib_storage_module() = snmpa_mib_data_ets | snmpa_mib_data_dets | snmpa_mib_data_mnesia | module()]]></c></tag> + <tag><marker id="agent_mst_module"></marker> + <c><![CDATA[mib_storage_module() = snmpa_mib_data_ets | snmpa_mib_data_dets | snmpa_mib_data_mnesia | module()]]></c></tag> <item> <p>Defines the mib storage module of the SNMP agent as defined by the <seealso marker="snmpa_mib_storage">snmpa_mib_storage</seealso> @@ -337,8 +338,8 @@ <p>Default module is <c>snmpa_mib_storage_ets</c>. </p> </item> - <marker id="agent_mst_options"></marker> - <tag><c><![CDATA[mib_storage_options() = list() <optional>]]></c></tag> + <tag><marker id="agent_mst_options"></marker> + <c><![CDATA[mib_storage_options() = list() <optional>]]></c></tag> <item> <p>This is implementattion depended. That is, it depends on the module. For each module a specific set of options are valid. @@ -427,16 +428,16 @@ </list> </item> - <marker id="agent_mib_server"></marker> - <tag><c><![CDATA[mib_server() = [mib_server_opt()] <optional>]]></c></tag> + <tag><marker id="agent_mib_server"></marker> + <c><![CDATA[mib_server() = [mib_server_opt()] <optional>]]></c></tag> <item> <p><c>mib_server_opt() = {mibentry_override, mibentry_override()} | {trapentry_override, trapentry_override()} | {verbosity, verbosity()} | {cache, mibs_cache()} | {data_module, mib_server_data_module()}</c></p> <p>Defines options specific for the SNMP agent mib server. </p> <p>For defaults see the options in <c>mib_server_opt()</c>.</p> </item> - <marker id="agent_ms_meo"></marker> - <tag><c><![CDATA[mibentry_override() = bool() <optional>]]></c></tag> + <tag><marker id="agent_ms_meo"></marker> + <c><![CDATA[mibentry_override() = bool() <optional>]]></c></tag> <item> <p>If this value is false, then when loading a mib each mib- entry is checked prior to installation of the mib. @@ -445,8 +446,8 @@ <p>Default is <c>false</c>.</p> </item> - <marker id="agent_ms_teo"></marker> - <tag><c><![CDATA[trapentry_override() = bool() <optional>]]></c></tag> + <tag><marker id="agent_ms_teo"></marker> + <c><![CDATA[trapentry_override() = bool() <optional>]]></c></tag> <item> <p>If this value is false, then when loading a mib each trap is checked prior to installation of the mib. @@ -455,11 +456,12 @@ <p>Default is <c>false</c>.</p> </item> - <marker id="agent_ms_data_module"></marker> <!-- - <tag><c><![CDATA[mib_server_data_module() = snmpa_mib_data_tttn | snmpa_mib_data_ttln | module() <optional>]]></c></tag> + <tag><marker id="agent_ms_data_module"></marker> + <c><![CDATA[mib_server_data_module() = snmpa_mib_data_tttn | snmpa_mib_data_ttln | module() <optional>]]></c></tag> --> - <tag><c><![CDATA[mib_server_data_module() = snmpa_mib_data_tttn | module() <optional>]]></c></tag> + <tag><marker id="agent_ms_data_module"></marker> + <c><![CDATA[mib_server_data_module() = snmpa_mib_data_tttn | module() <optional>]]></c></tag> <item> <p>Defines the backend data module of the SNMP agent mib-server as defined by the @@ -476,24 +478,24 @@ <p>Default module is <c>snmpa_mib_data_tttn</c>. </p> </item> - <marker id="agent_ms_cache"></marker> - <tag><c><![CDATA[mibs_cache() = bool() | mibs_cache_opts() <optional>]]></c></tag> + <tag><marker id="agent_ms_cache"></marker> + <c><![CDATA[mibs_cache() = bool() | mibs_cache_opts() <optional>]]></c></tag> <item> <p>Shall the agent utilize the mib server lookup cache or not.</p> <p>Default is <c>true</c> (in which case the <c>mibs_cache_opts()</c> default values apply).</p> </item> - <marker id="agent_ms_cache_opts"></marker> - <tag><c><![CDATA[mibs_cache_opts() = [mibs_cache_opt()] <optional>]]></c></tag> + <tag><marker id="agent_ms_cache_opts"></marker> + <c><![CDATA[mibs_cache_opts() = [mibs_cache_opt()] <optional>]]></c></tag> <item> <p><c>mibs_cache_opt() = {autogc, mibs_cache_autogc()} | {gclimit, mibs_cache_gclimit()} | {age, mibs_cache_age()}</c></p> <p>Defines options specific for the SNMP agent mib server cache. </p> <p>For defaults see the options in <c>mibs_cache_opt()</c>.</p> </item> - <marker id="agent_ms_cache_autogc"></marker> - <tag><c><![CDATA[mibs_cache_autogc() = bool() <optional>]]></c></tag> + <tag><marker id="agent_ms_cache_autogc"></marker> + <c><![CDATA[mibs_cache_autogc() = bool() <optional>]]></c></tag> <item> <p>Defines if the mib server shall perform cache gc automatically or leave it to the user (see @@ -501,8 +503,8 @@ <p>Default is <c>true</c>.</p> </item> - <marker id="agent_ms_cache_age"></marker> - <tag><c><![CDATA[mibs_cache_age() = integer() > 0 <optional>]]></c></tag> + <tag><marker id="agent_ms_cache_age"></marker> + <c><![CDATA[mibs_cache_age() = integer() > 0 <optional>]]></c></tag> <item> <p>Defines how old the entries in the cache will be allowed to become before they are GC'ed (assuming GC is performed). @@ -511,8 +513,8 @@ <p>Default is <c>10 timutes</c>.</p> </item> - <marker id="agent_ms_cache_gclimit"></marker> - <tag><c><![CDATA[mibs_cache_gclimit() = integer() > 0 | infinity <optional>]]></c></tag> + <tag><marker id="agent_ms_cache_gclimit"></marker> + <c><![CDATA[mibs_cache_gclimit() = integer() > 0 | infinity <optional>]]></c></tag> <item> <p>When performing a GC, this is the max number of cache entries that will be deleted from the cache. </p> @@ -522,8 +524,8 @@ <p>Default is <c>100</c>.</p> </item> - <marker id="agent_error_report_mod"></marker> - <tag><c><![CDATA[error_report_mod() = atom() <optional>]]></c></tag> + <tag><marker id="agent_error_report_mod"></marker> + <c><![CDATA[error_report_mod() = atom() <optional>]]></c></tag> <item> <p>Defines an error report module, implementing the <seealso marker="snmpa_error_report">snmpa_error_report</seealso> @@ -532,38 +534,38 @@ <p>Default is <c>snmpa_error_logger</c>.</p> </item> - <marker id="agent_symbolic_store"></marker> - <tag><c>symbolic_store() = [symbolic_store_opt()]</c></tag> + <tag><marker id="agent_symbolic_store"></marker> + <c>symbolic_store() = [symbolic_store_opt()]</c></tag> <item> <p><c>symbolic_store_opt() = {verbosity, verbosity()}</c></p> <p>Defines options specific for the SNMP agent symbolic store. </p> <p>For defaults see the options in <c>symbolic_store_opt()</c>.</p> </item> - <marker id="agent_target_cache"></marker> - <tag><c>target_cache() = [target_cache_opt()]</c></tag> + <tag><marker id="agent_target_cache"></marker> + <c>target_cache() = [target_cache_opt()]</c></tag> <item> <p><c>target_cache_opt() = {verbosity, verbosity()}</c></p> <p>Defines options specific for the SNMP agent target cache. </p> <p>For defaults see the options in <c>target_cache_opt()</c>.</p> </item> - <marker id="agent_config"></marker> - <tag><c><![CDATA[agent_config() = [agent_config_opt()] <mandatory>]]></c></tag> + <tag><marker id="agent_config"></marker> + <c><![CDATA[agent_config() = [agent_config_opt()] <mandatory>]]></c></tag> <item> <p><c>agent_config_opt() = {dir, agent_config_dir()} | {force_load, force_load()} | {verbosity, verbosity()}</c></p> <p>Defines specific config related options for the SNMP agent. </p> <p>For defaults see the options in <c>agent_config_opt()</c>.</p> </item> - <marker id="agent_config_dir"></marker> - <tag><c><![CDATA[agent_config_dir = dir() <mandatory>]]></c></tag> + <tag><marker id="agent_config_dir"></marker> + <c><![CDATA[agent_config_dir = dir() <mandatory>]]></c></tag> <item> <p>Defines where the SNMP agent configuration files are stored.</p> </item> - <marker id="agent_force_load"></marker> - <tag><c><![CDATA[force_load() = bool() <optional>]]></c></tag> + <tag><marker id="agent_force_load"></marker> + <c><![CDATA[force_load() = bool() <optional>]]></c></tag> <item> <p>If <c>true</c> the configuration files are re-read during start-up, and the contents of the configuration @@ -577,16 +579,16 @@ <marker id="manager_opts_and_types"></marker> <p>Manager specific config options and types:</p> <taglist> - <marker id="manager_server"></marker> - <tag><c><![CDATA[server() = [server_opt()] <optional>]]></c></tag> + <tag><marker id="manager_server"></marker> + <c><![CDATA[server() = [server_opt()] <optional>]]></c></tag> <item> <p><c>server_opt() = {timeout, server_timeout()} | {verbosity, verbosity()}</c></p> <p>Specifies the options for the manager server process.</p> <p>Default is <c>silence</c>.</p> </item> - <marker id="manager_server_timeout"></marker> - <tag><c><![CDATA[server_timeout() = integer() <optional>]]></c></tag> + <tag><marker id="manager_server_timeout"></marker> + <c><![CDATA[server_timeout() = integer() <optional>]]></c></tag> <item> <p>Asynchronous request cleanup time. For every requests, some info is stored internally, in order to be able to @@ -606,44 +608,44 @@ <p>Default is <c>30000</c>.</p> </item> - <marker id="manager_config"></marker> - <tag><c><![CDATA[manager_config() = [manager_config_opt()] <mandatory>]]></c></tag> + <tag><marker id="manager_config"></marker> + <c><![CDATA[manager_config() = [manager_config_opt()] <mandatory>]]></c></tag> <item> <p><c>manager_config_opt() = {dir, manager_config_dir()} | {db_dir, manager_db_dir()} | {db_init_error, db_init_error()} | {repair, manager_repair()} | {auto_save, manager_auto_save()} | {verbosity, verbosity()}</c></p> <p>Defines specific config related options for the SNMP manager. </p> <p>For defaults see the options in <c>manager_config_opt()</c>.</p> </item> - <marker id="manager_config_dir"></marker> - <tag><c><![CDATA[manager_config_dir = dir() <mandatory>]]></c></tag> + <tag><marker id="manager_config_dir"></marker> + <c><![CDATA[manager_config_dir = dir() <mandatory>]]></c></tag> <item> <p>Defines where the SNMP manager configuration files are stored.</p> </item> - <marker id="manager_config_db_dir"></marker> - <tag><c><![CDATA[manager_db_dir = dir() <mandatory>]]></c></tag> + <tag><marker id="manager_config_db_dir"></marker> + <c><![CDATA[manager_db_dir = dir() <mandatory>]]></c></tag> <item> <p>Defines where the SNMP manager store persistent data.</p> </item> - <marker id="manager_config_repair"></marker> - <tag><c><![CDATA[manager_repair() = false | true | force <optional>]]></c></tag> + <tag><marker id="manager_config_repair"></marker> + <c><![CDATA[manager_repair() = false | true | force <optional>]]></c></tag> <item> <p>Defines the repair option for the persistent database (if and how the table is repaired when opened). </p> <p>Default is <c>true</c>.</p> </item> - <marker id="manager_config_auto_save"></marker> - <tag><c><![CDATA[manager_auto_save() = integer() | infinity <optional>]]></c></tag> + <tag><marker id="manager_config_auto_save"></marker> + <c><![CDATA[manager_auto_save() = integer() | infinity <optional>]]></c></tag> <item> <p>The auto save interval. The table is flushed to disk whenever not accessed for this amount of time.</p> <p>Default is <c>5000</c>.</p> </item> - <marker id="manager_irb"></marker> - <tag><c><![CDATA[manager_irb() = auto | user | {user, integer()} <optional>]]></c></tag> + <tag><marker id="manager_irb"></marker> + <c><![CDATA[manager_irb() = auto | user | {user, integer()} <optional>]]></c></tag> <item> <p>This option defines how the manager will handle the sending of response (acknowledgment) to received inform-requests. </p> @@ -672,16 +674,16 @@ <p>Default is <c>auto</c>.</p> </item> - <marker id="manager_mibs"></marker> - <tag><c><![CDATA[manager_mibs() = [string()] <optional>]]></c></tag> + <tag><marker id="manager_mibs"></marker> + <c><![CDATA[manager_mibs() = [string()] <optional>]]></c></tag> <item> <p>Specifies a list of MIBs (including path) and defines which MIBs are initially loaded into the SNMP manager. </p> <p>Default is <c>[]</c>.</p> </item> - <marker id="manager_net_if"></marker> - <tag><c><![CDATA[manager_net_if() = [manager_net_if_opt()] <optional>]]></c></tag> + <tag><marker id="manager_net_if"></marker> + <c><![CDATA[manager_net_if() = [manager_net_if_opt()] <optional>]]></c></tag> <item> <p><c>manager_net_if_opt() = {module, manager_net_if_module()} | {verbosity, verbosity()} | @@ -691,8 +693,8 @@ <p>For defaults see the options in <c>manager_net_if_opt()</c>.</p> </item> - <marker id="manager_ni_opts"></marker> - <tag><c><![CDATA[manager_net_if_options() = [manager_net_if_option()] <optional>]]></c></tag> + <tag><marker id="manager_ni_opts"></marker> + <c><![CDATA[manager_net_if_options() = [manager_net_if_option()] <optional>]]></c></tag> <item> <p><c>manager_net_if_option() = {bind_to, bind_to()} | {sndbuf, sndbuf()} | @@ -705,8 +707,8 @@ <p>For defaults see the options in <c>manager_net_if_option()</c>.</p> </item> - <marker id="manager_ni_module"></marker> - <tag><c><![CDATA[manager_net_if_module() = atom() <optional>]]></c></tag> + <tag><marker id="manager_ni_module"></marker> + <c><![CDATA[manager_net_if_module() = atom() <optional>]]></c></tag> <item> <p>The module which handles the network interface part for the SNMP manager. It must implement the @@ -714,8 +716,8 @@ <p>Default is <c>snmpm_net_if</c>.</p> </item> - <marker id="manager_ni_filter_opts"></marker> - <tag><c><![CDATA[manager_net_if_filter_options() = [manager_net_if_filter_option()] <optional>]]></c></tag> + <tag><marker id="manager_ni_filter_opts"></marker> + <c><![CDATA[manager_net_if_filter_options() = [manager_net_if_filter_option()] <optional>]]></c></tag> <item> <p><c>manager_net_if_filter_option() = {module, manager_net_if_filter_module()}</c></p> <p>These options are actually specific to the used module. @@ -725,8 +727,8 @@ <c>manager_net_if_filter_option()</c>.</p> </item> - <marker id="manager_ni_filter_module"></marker> - <tag><c><![CDATA[manager_net_if_filter_module() = atom() <optional>]]></c></tag> + <tag><marker id="manager_ni_filter_module"></marker> + <c><![CDATA[manager_net_if_filter_module() = atom() <optional>]]></c></tag> <item> <p>Module which handles the network interface filter part for the SNMP manager. Must implement the @@ -734,16 +736,16 @@ <p>Default is <c>snmpm_net_if_filter</c>.</p> </item> - <marker id="manager_def_user_module"></marker> - <tag><c><![CDATA[def_user_module() = atom() <optional>]]></c></tag> + <tag><marker id="manager_def_user_module"></marker> + <c><![CDATA[def_user_module() = atom() <optional>]]></c></tag> <item> <p>The module implementing the default user. See the <seealso marker="snmpm_user">snmpm_user</seealso> behaviour.</p> <p>Default is <c>snmpm_user_default</c>.</p> </item> - <marker id="manager_def_user_data"></marker> - <tag><c><![CDATA[def_user_data() = term() <optional>]]></c></tag> + <tag><marker id="manager_def_user_data"></marker> + <c><![CDATA[def_user_data() = term() <optional>]]></c></tag> <item> <p>Data for the default user. Passed to the user module when calling the callback functions.</p> @@ -754,8 +756,8 @@ <marker id="common_types"></marker> <p>Common config types:</p> <taglist> - <marker id="restart_type"></marker> - <tag><c>restart_type() = permanent | transient | temporary</c></tag> + <tag><marker id="restart_type"></marker> + <c>restart_type() = permanent | transient | temporary</c></tag> <item> <p>See <seealso marker="stdlib:supervisor#child_spec">supervisor</seealso> documentation for more info.</p> @@ -763,8 +765,8 @@ for the manager.</p> </item> - <marker id="db_init_error"></marker> - <tag><c>db_init_error() = terminate | create | create_db_and_dir</c></tag> + <tag><marker id="db_init_error"></marker> + <c>db_init_error() = terminate | create | create_db_and_dir</c></tag> <item> <p>Defines what to do if the agent or manager is unable to open an existing database file. <c>terminate</c> means that the @@ -776,31 +778,31 @@ <p>Default is <c>terminate</c>.</p> </item> - <marker id="prio"></marker> - <tag><c><![CDATA[priority() = atom() <optional>]]></c></tag> + <tag><marker id="prio"></marker> + <c><![CDATA[priority() = atom() <optional>]]></c></tag> <item> <p>Defines the Erlang priority for all SNMP processes.</p> <p>Default is <c>normal</c>.</p> </item> - <marker id="versions"></marker> - <tag><c><![CDATA[versions() = [version()] <optional>]]></c></tag> + <tag><marker id="versions"></marker> + <c><![CDATA[versions() = [version()] <optional>]]></c></tag> <item> <p><c>version() = v1 | v2 | v3</c></p> <p>Which SNMP versions shall be accepted/used.</p> <p>Default is <c>[v1,v2,v3]</c>.</p> </item> - <marker id="verbosity"></marker> - <tag><c><![CDATA[verbosity() = silence | info | log | debug | trace <optional>]]></c></tag> + <tag><marker id="verbosity"></marker> + <c><![CDATA[verbosity() = silence | info | log | debug | trace <optional>]]></c></tag> <item> <p>Verbosity for a SNMP process. This specifies now much debug info is printed.</p> <p>Default is <c>silence</c>.</p> </item> - <marker id="bind_to"></marker> - <tag><c><![CDATA[bind_to() = bool() <optional>]]></c></tag> + <tag><marker id="bind_to"></marker> + <c><![CDATA[bind_to() = bool() <optional>]]></c></tag> <item> <p>If <c>true</c>, net_if binds to the IP address. If <c>false</c>, net_if listens on any IP address on the host @@ -808,8 +810,8 @@ <p>Default is <c>false</c>.</p> </item> - <marker id="no_reuse"></marker> - <tag><c><![CDATA[no_reuse() = bool() <optional>]]></c></tag> + <tag><marker id="no_reuse"></marker> + <c><![CDATA[no_reuse() = bool() <optional>]]></c></tag> <item> <p>If <c>true</c>, net_if does not specify that the IP and port address should be reusable. If <c>false</c>, @@ -817,30 +819,30 @@ <p>Default is <c>false</c>.</p> </item> - <marker id="recbuf"></marker> - <tag><c><![CDATA[recbuf() = integer() <optional>]]></c></tag> + <tag><marker id="recbuf"></marker> + <c><![CDATA[recbuf() = integer() <optional>]]></c></tag> <item> <p>Receive buffer size. </p> <p>Default value is defined by <c>gen_udp</c>.</p> </item> - <marker id="sndbuf"></marker> - <tag><c><![CDATA[sndbuf() = integer() <optional>]]></c></tag> + <tag><marker id="sndbuf"></marker> + <c><![CDATA[sndbuf() = integer() <optional>]]></c></tag> <item> <p>Send buffer size. </p> <p>Default value is defined by <c>gen_udp</c>.</p> </item> - <marker id="note_store"></marker> - <tag><c><![CDATA[note_store() = [note_store_opt()] <optional>]]></c></tag> + <tag><marker id="note_store"></marker> + <c><![CDATA[note_store() = [note_store_opt()] <optional>]]></c></tag> <item> <p><c>note_store_opt() = {timeout, note_store_timeout()} | {verbosity, verbosity()}</c></p> <p>Specifies the start-up verbosity for the SNMP note store.</p> <p>For defaults see the options in <c>note_store_opt()</c>.</p> </item> - <marker id="ns_timeout"></marker> - <tag><c><![CDATA[note_store_timeout() = integer() <optional>]]></c></tag> + <tag><marker id="ns_timeout"></marker> + <c><![CDATA[note_store_timeout() = integer() <optional>]]></c></tag> <item> <p>Note cleanup time. When storing a note in the note store, each note is given lifetime. Every <c>timeout</c> the note_store @@ -850,8 +852,8 @@ </item> - <marker id="audit_trail_log"></marker> - <tag><c><![CDATA[audit_trail_log() = [audit_trail_log_opt()] <optional>]]></c></tag> + <tag><marker id="audit_trail_log"></marker> + <c><![CDATA[audit_trail_log() = [audit_trail_log_opt()] <optional>]]></c></tag> <item> <p><c>audit_trail_log_opt() = {type, atl_type()} | {dir, atl_dir()} | {size, atl_size()} | {repair, atl_repair()} | {seqno, atl_seqno()}</c></p> <p>If present, this option specifies the options for the @@ -861,8 +863,8 @@ <p>If not present, audit trail logging is not used.</p> </item> - <marker id="atl_type"></marker> - <tag><c><![CDATA[atl_type() = read | write | read_write <optional>]]></c></tag> + <tag><marker id="atl_type"></marker> + <c><![CDATA[atl_type() = read | write | read_write <optional>]]></c></tag> <item> <p>Specifies what type of an audit trail log should be used. The effect of the type is actually different for the the agent @@ -883,16 +885,16 @@ <p>Default is <c>read_write</c>.</p> </item> - <marker id="atl_dir"></marker> - <tag><c><![CDATA[atl_dir = dir() <mandatory>]]></c></tag> + <tag><marker id="atl_dir"></marker> + <c><![CDATA[atl_dir = dir() <mandatory>]]></c></tag> <item> <p>Specifies where the audit trail log should be stored.</p> <p>If <c>audit_trail_log</c> specifies that logging should take place, this parameter <em>must</em> be defined.</p> </item> - <marker id="atl_size"></marker> - <tag><c><![CDATA[atl_size() = {integer(), integer()} <mandatory>]]></c></tag> + <tag><marker id="atl_size"></marker> + <c><![CDATA[atl_size() = {integer(), integer()} <mandatory>]]></c></tag> <item> <p>Specifies the size of the audit trail log. This parameter is sent to <c>disk_log</c>. </p> @@ -900,8 +902,8 @@ take place, this parameter <em>must</em> be defined.</p> </item> - <marker id="atl_repair"></marker> - <tag><c><![CDATA[atl_repair() = true | false | truncate | snmp_repair <optional>]]></c></tag> + <tag><marker id="atl_repair"></marker> + <c><![CDATA[atl_repair() = true | false | truncate | snmp_repair <optional>]]></c></tag> <item> <p>Specifies if and how the audit trail log shall be repaired when opened. Unless this parameter has the value <c>snmp_repair</c> @@ -913,8 +915,8 @@ <p>Default is <c>true</c>.</p> </item> - <marker id="atl_seqno"></marker> - <tag><c><![CDATA[atl_seqno() = true | false <optional>]]></c></tag> + <tag><marker id="atl_seqno"></marker> + <c><![CDATA[atl_seqno() = true | false <optional>]]></c></tag> <item> <p>Specifies if the audit trail log entries will be (sequence) numbered or not. The range of the sequence numbers are according diff --git a/lib/snmp/doc/src/snmp_config.xml b/lib/snmp/doc/src/snmp_config.xml index f10574a2a9..a085252d90 100644 --- a/lib/snmp/doc/src/snmp_config.xml +++ b/lib/snmp/doc/src/snmp_config.xml @@ -130,16 +130,16 @@ <marker id="agent_opts_and_types"></marker> <p>Agent specific config options and types:</p> <taglist> - <marker id="agent_type"></marker> - <tag><c><![CDATA[agent_type() = master | sub <optional>]]></c></tag> + <tag><marker id="agent_type"></marker> + <c><![CDATA[agent_type() = master | sub <optional>]]></c></tag> <item> <p>If <c>master</c>, one master agent is started. Otherwise, no agents are started. </p> <p>Default is <c>master</c>.</p> </item> - <marker id="agent_disco"></marker> - <tag><c><![CDATA[agent_discovery() = [agent_discovery_opt()] <optional>]]></c></tag> + <tag><marker id="agent_disco"></marker> + <c><![CDATA[agent_discovery() = [agent_discovery_opt()] <optional>]]></c></tag> <item> <p><c>agent_discovery_opt() = {terminating, agent_terminating_discovery_opts()} | @@ -151,8 +151,8 @@ <p>For defaults see the options in <c>agent_discovery_opt()</c>.</p> </item> - <marker id="agent_term_disco_opts"></marker> - <tag><c><![CDATA[agent_terminating_discovery_opts() = [agent_terminating_discovery_opt()] <optional>]]></c></tag> + <tag><marker id="agent_term_disco_opts"></marker> + <c><![CDATA[agent_terminating_discovery_opts() = [agent_terminating_discovery_opt()] <optional>]]></c></tag> <item> <p><c>agent_terminating_discovery_opt() = {enable, boolean()} | @@ -169,8 +169,8 @@ </list> </item> - <marker id="agent_orig_disco_opts"></marker> - <tag><c><![CDATA[agent_originating_discovery_opts() = [agent_originating_discovery_opt()] <optional>]]></c></tag> + <tag><marker id="agent_orig_disco_opts"></marker> + <c><![CDATA[agent_originating_discovery_opts() = [agent_originating_discovery_opt()] <optional>]]></c></tag> <item> <p><c>agent_originating_discovery_opt() = {enable, boolean()}</c></p> @@ -183,38 +183,38 @@ </list> </item> - <marker id="agent_mt"></marker> - <tag><c><![CDATA[multi_threaded() = bool() <optional>]]></c></tag> + <tag><marker id="agent_mt"></marker> + <c><![CDATA[multi_threaded() = bool() <optional>]]></c></tag> <item> <p>If <c>true</c>, the agent is multi-threaded, with one thread for each get request. </p> <p>Default is <c>false</c>.</p> </item> - <marker id="agent_data_dir"></marker> - <tag><c><![CDATA[db_dir() = string() <mandatory>]]></c></tag> + <tag><marker id="agent_data_dir"></marker> + <c><![CDATA[db_dir() = string() <mandatory>]]></c></tag> <item> <p>Defines where the SNMP agent internal db files are stored.</p> </item> - <marker id="agent_gb_max_vbs"></marker> - <tag><c><![CDATA[gb_max_vbs() = pos_integer() | infinity <optional>]]></c></tag> + <tag><marker id="agent_gb_max_vbs"></marker> + <c><![CDATA[gb_max_vbs() = pos_integer() | infinity <optional>]]></c></tag> <item> <p>Defines the maximum number of varbinds allowed in a Get-BULK response.</p> <p>Default is <c>1000</c>.</p> </item> - <marker id="agent_local_db"></marker> - <tag><c><![CDATA[local_db() = [local_db_opt()] <optional>]]></c></tag> + <tag><marker id="agent_local_db"></marker> + <c><![CDATA[local_db() = [local_db_opt()] <optional>]]></c></tag> <item> <p><c>local_db_opt() = {repair, agent_repair()} | {auto_save, agent_auto_save()} | {verbosity, verbosity()}</c></p> <p>Defines options specific for the SNMP agent local database.</p> <p>For defaults see the options in <c>local_db_opt()</c>.</p> </item> - <marker id="agent_ldb_repair"></marker> - <tag><c><![CDATA[agent_repair() = false | true | force <optional>]]></c></tag> + <tag><marker id="agent_ldb_repair"></marker> + <c><![CDATA[agent_repair() = false | true | force <optional>]]></c></tag> <item> <p>When starting snmpa_local_db it always tries to open an existing database. If <c>false</c>, and some errors occur, a new @@ -224,16 +224,16 @@ <p>Default is <c>true</c>.</p> </item> - <marker id="agent_ldb_auto_save"></marker> - <tag><c><![CDATA[agent_auto_save() = integer() | infinity <optional>]]></c></tag> + <tag><marker id="agent_ldb_auto_save"></marker> + <c><![CDATA[agent_auto_save() = integer() | infinity <optional>]]></c></tag> <item> <p>The auto save interval. The table is flushed to disk whenever not accessed for this amount of time.</p> <p>Default is <c>5000</c>.</p> </item> - <marker id="agent_net_if"></marker> - <tag><c><![CDATA[agent_net_if() = [agent_net_if_opt()] <optional>]]></c></tag> + <tag><marker id="agent_net_if"></marker> + <c><![CDATA[agent_net_if() = [agent_net_if_opt()] <optional>]]></c></tag> <item> <p><c>agent_net_if_option() = {module, agent_net_if_module()} | {verbosity, verbosity()} | @@ -243,8 +243,8 @@ <p>For defaults see the options in <c>agent_net_if_opt()</c>.</p> </item> - <marker id="agent_ni_module"></marker> - <tag><c><![CDATA[agent_net_if_module() = atom() <optional>]]></c></tag> + <tag><marker id="agent_ni_module"></marker> + <c><![CDATA[agent_net_if_module() = atom() <optional>]]></c></tag> <item> <p>Module which handles the network interface part for the SNMP agent. Must implement the @@ -252,8 +252,8 @@ <p>Default is <c>snmpa_net_if</c>.</p> </item> - <marker id="agent_ni_opts"></marker> - <tag><c><![CDATA[agent_net_if_options() = [agent_net_if_option()] <optional>]]></c></tag> + <tag><marker id="agent_ni_opts"></marker> + <c><![CDATA[agent_net_if_options() = [agent_net_if_option()] <optional>]]></c></tag> <item> <p><c>agent_net_if_option() = {bind_to, bind_to()} | {sndbuf, sndbuf()} | @@ -267,15 +267,15 @@ <p>For defaults see the options in <c>agent_net_if_option()</c>.</p> </item> - <marker id="agent_ni_req_limit"></marker> - <tag><c><![CDATA[req_limit() = integer() | infinity <optional>]]></c></tag> + <tag><marker id="agent_ni_req_limit"></marker> + <c><![CDATA[req_limit() = integer() | infinity <optional>]]></c></tag> <item> <p>Max number of simultaneous requests handled by the agent.</p> <p>Default is <c>infinity</c>.</p> </item> - <marker id="agent_ni_filter_opts"></marker> - <tag><c><![CDATA[agent_net_if_filter_options() = [agent_net_if_filter_option()] <optional>]]></c></tag> + <tag><marker id="agent_ni_filter_opts"></marker> + <c><![CDATA[agent_net_if_filter_options() = [agent_net_if_filter_option()] <optional>]]></c></tag> <item> <p><c><![CDATA[agent_net_if_filter_option() = {module, agent_net_if_filter_module()}]]></c></p> <p>These options are actually specific to the used module. @@ -284,8 +284,8 @@ <p>For defaults see the options in <c>agent_net_if_filter_option()</c>.</p> </item> - <marker id="agent_ni_filter_module"></marker> - <tag><c><![CDATA[agent_net_if_filter_module() = atom() <optional>]]></c></tag> + <tag><marker id="agent_ni_filter_module"></marker> + <c><![CDATA[agent_net_if_filter_module() = atom() <optional>]]></c></tag> <item> <p>Module which handles the network interface filter part for the SNMP agent. Must implement the @@ -294,8 +294,8 @@ <p>Default is <c>snmpa_net_if_filter</c>.</p> </item> - <marker id="agent_mibs"></marker> - <tag><c><![CDATA[agent_mibs() = [string()] <optional>]]></c></tag> + <tag><marker id="agent_mibs"></marker> + <c><![CDATA[agent_mibs() = [string()] <optional>]]></c></tag> <item> <p>Specifies a list of MIBs (including path) that defines which MIBs are initially loaded into the SNMP master agent. </p> @@ -309,8 +309,8 @@ <p>Default is <c>[]</c>.</p> </item> - <marker id="agent_mib_storage"></marker> - <tag><c><![CDATA[mib_storage() = [mib_storage_opt()] <optional>]]></c></tag> + <tag><marker id="agent_mib_storage"></marker> + <c><![CDATA[mib_storage() = [mib_storage_opt()] <optional>]]></c></tag> <item> <p><c>mib_storage_opt() = {module, mib_storage_module()} | {options, mib_storage_options()}</c></p> <p>This option specifies how basic mib data is stored. @@ -319,8 +319,8 @@ <p>Default is <c>[{module, snmpa_mib_storage_ets}]</c>. </p> </item> - <marker id="agent_mst_module"></marker> - <tag><c><![CDATA[mib_storage_module() = snmpa_mib_data_ets | snmpa_mib_data_dets | snmpa_mib_data_mnesia | module()]]></c></tag> + <tag><marker id="agent_mst_module"></marker> + <c><![CDATA[mib_storage_module() = snmpa_mib_data_ets | snmpa_mib_data_dets | snmpa_mib_data_mnesia | module()]]></c></tag> <item> <p>Defines the mib storage module of the SNMP agent as defined by the <seealso marker="snmpa_mib_storage">snmpa_mib_storage</seealso> @@ -334,8 +334,8 @@ <p>Default module is <c>snmpa_mib_storage_ets</c>. </p> </item> - <marker id="agent_mst_options"></marker> - <tag><c><![CDATA[mib_storage_options() = list() <optional>]]></c></tag> + <tag><marker id="agent_mst_options"></marker> + <c><![CDATA[mib_storage_options() = list() <optional>]]></c></tag> <item> <p>This is implementattion depended. That is, it depends on the module. For each module a specific set of options are valid. @@ -429,8 +429,8 @@ This is the old format which is "supported", but not documented, in so far as it will be converted to the new format if found. - <marker id="agent_mib_storage"></marker> - <tag><c><![CDATA[mib_storage() = ets | {ets, Dir} | {ets, Dir, Action} | dets | {dets, Dir} | {dets, Dir, Action} | mnesia | {mnesia, Nodes} | {mnesia, Nodes, Action} <optional>]]></c></tag> + <tag><marker id="agent_mib_storage"></marker> + <c><![CDATA[mib_storage() = ets | {ets, Dir} | {ets, Dir, Action} | dets | {dets, Dir} | {dets, Dir, Action} | mnesia | {mnesia, Nodes} | {mnesia, Nodes, Action} <optional>]]></c></tag> <item> <p>Specifies how info retrieved from the mibs will be stored.</p> <p>If <c>mib_storage</c> is <c>{ets, Dir}</c>, the table will also be @@ -456,16 +456,16 @@ in so far as it will be converted to the new format if found. </item> --> - <marker id="agent_mib_server"></marker> - <tag><c><![CDATA[mib_server() = [mib_server_opt()] <optional>]]></c></tag> + <tag><marker id="agent_mib_server"></marker> + <c><![CDATA[mib_server() = [mib_server_opt()] <optional>]]></c></tag> <item> <p><c>mib_server_opt() = {mibentry_override, mibentry_override()} | {trapentry_override, trapentry_override()} | {verbosity, verbosity()} | {cache, mibs_cache()} | {data_module, mib_server_data_module()}</c></p> <p>Defines options specific for the SNMP agent mib server. </p> <p>For defaults see the options in <c>mib_server_opt()</c>.</p> </item> - <marker id="agent_ms_meo"></marker> - <tag><c><![CDATA[mibentry_override() = bool() <optional>]]></c></tag> + <tag><marker id="agent_ms_meo"></marker> + <c><![CDATA[mibentry_override() = bool() <optional>]]></c></tag> <item> <p>If this value is false, then when loading a mib each mib- entry is checked prior to installation of the mib. @@ -474,8 +474,8 @@ in so far as it will be converted to the new format if found. <p>Default is <c>false</c>.</p> </item> - <marker id="agent_ms_teo"></marker> - <tag><c><![CDATA[trapentry_override() = bool() <optional>]]></c></tag> + <tag><marker id="agent_ms_teo"></marker> + <c><![CDATA[trapentry_override() = bool() <optional>]]></c></tag> <item> <p>If this value is false, then when loading a mib each trap is checked prior to installation of the mib. @@ -484,11 +484,13 @@ in so far as it will be converted to the new format if found. <p>Default is <c>false</c>.</p> </item> - <marker id="agent_ms_data_module"></marker> + <!-- - <tag><c><![CDATA[mib_server_data_module() = snmpa_mib_data_tttn | snmpa_mib_data_ttln | module() <optional>]]></c></tag> + <tag><marker id="agent_ms_data_module"></marker> + <c><![CDATA[mib_server_data_module() = snmpa_mib_data_tttn | snmpa_mib_data_ttln | module() <optional>]]></c></tag> --> - <tag><c><![CDATA[mib_server_data_module() = snmpa_mib_data_tttn | module() <optional>]]></c></tag> + <tag><marker id="agent_ms_data_module"></marker> + <c><![CDATA[mib_server_data_module() = snmpa_mib_data_tttn | module() <optional>]]></c></tag> <item> <p>Defines the backend data module of the SNMP agent mib-server as defined by the @@ -505,24 +507,24 @@ in so far as it will be converted to the new format if found. <p>Default module is <c>snmpa_mib_data_tttn</c>. </p> </item> - <marker id="agent_ms_cache"></marker> - <tag><c><![CDATA[mibs_cache() = bool() | mibs_cache_opts() <optional>]]></c></tag> + <tag><marker id="agent_ms_cache"></marker> + <c><![CDATA[mibs_cache() = bool() | mibs_cache_opts() <optional>]]></c></tag> <item> <p>Shall the agent utilize the mib server lookup cache or not.</p> <p>Default is <c>true</c> (in which case the <c>mibs_cache_opts()</c> default values apply).</p> </item> - <marker id="agent_ms_cache_opts"></marker> - <tag><c><![CDATA[mibs_cache_opts() = [mibs_cache_opt()] <optional>]]></c></tag> + <tag><marker id="agent_ms_cache_opts"></marker> + <c><![CDATA[mibs_cache_opts() = [mibs_cache_opt()] <optional>]]></c></tag> <item> <p><c>mibs_cache_opt() = {autogc, mibs_cache_autogc()} | {gclimit, mibs_cache_gclimit()} | {age, mibs_cache_age()}</c></p> <p>Defines options specific for the SNMP agent mib server cache. </p> <p>For defaults see the options in <c>mibs_cache_opt()</c>.</p> </item> - <marker id="agent_ms_cache_autogc"></marker> - <tag><c><![CDATA[mibs_cache_autogc() = bool() <optional>]]></c></tag> + <tag><marker id="agent_ms_cache_autogc"></marker> + <c><![CDATA[mibs_cache_autogc() = bool() <optional>]]></c></tag> <item> <p>Defines if the mib server shall perform cache gc automatically or leave it to the user (see @@ -530,8 +532,8 @@ in so far as it will be converted to the new format if found. <p>Default is <c>true</c>.</p> </item> - <marker id="agent_ms_cache_age"></marker> - <tag><c><![CDATA[mibs_cache_age() = integer() > 0 <optional>]]></c></tag> + <tag><marker id="agent_ms_cache_age"></marker> + <c><![CDATA[mibs_cache_age() = integer() > 0 <optional>]]></c></tag> <item> <p>Defines how old the entries in the cache will be allowed to become before they are GC'ed (assuming GC is performed). @@ -540,8 +542,8 @@ in so far as it will be converted to the new format if found. <p>Default is <c>10 timutes</c>.</p> </item> - <marker id="agent_ms_cache_gclimit"></marker> - <tag><c><![CDATA[mibs_cache_gclimit() = integer() > 0 | infinity <optional>]]></c></tag> + <tag><marker id="agent_ms_cache_gclimit"></marker> + <c><![CDATA[mibs_cache_gclimit() = integer() > 0 | infinity <optional>]]></c></tag> <item> <p>When performing a GC, this is the max number of cache entries that will be deleted from the cache. </p> @@ -551,8 +553,8 @@ in so far as it will be converted to the new format if found. <p>Default is <c>100</c>.</p> </item> - <marker id="agent_error_report_mod"></marker> - <tag><c><![CDATA[error_report_mod() = atom() <optional>]]></c></tag> + <tag><marker id="agent_error_report_mod"></marker> + <c><![CDATA[error_report_mod() = atom() <optional>]]></c></tag> <item> <p>Defines an error report module, implementing the <seealso marker="snmpa_error_report">snmpa_error_report</seealso> @@ -561,38 +563,38 @@ in so far as it will be converted to the new format if found. <p>Default is <c>snmpa_error_logger</c>.</p> </item> - <marker id="agent_symbolic_store"></marker> - <tag><c>symbolic_store() = [symbolic_store_opt()]</c></tag> + <tag><marker id="agent_symbolic_store"></marker> + <c>symbolic_store() = [symbolic_store_opt()]</c></tag> <item> <p><c>symbolic_store_opt() = {verbosity, verbosity()}</c></p> <p>Defines options specific for the SNMP agent symbolic store. </p> <p>For defaults see the options in <c>symbolic_store_opt()</c>.</p> </item> - <marker id="agent_target_cache"></marker> - <tag><c>target_cache() = [target_cache_opt()]</c></tag> + <tag><marker id="agent_target_cache"></marker> + <c>target_cache() = [target_cache_opt()]</c></tag> <item> <p><c>target_cache_opt() = {verbosity, verbosity()}</c></p> <p>Defines options specific for the SNMP agent target cache. </p> <p>For defaults see the options in <c>target_cache_opt()</c>.</p> </item> - <marker id="agent_config"></marker> - <tag><c><![CDATA[agent_config() = [agent_config_opt()] <mandatory>]]></c></tag> + <tag><marker id="agent_config"></marker> + <c><![CDATA[agent_config() = [agent_config_opt()] <mandatory>]]></c></tag> <item> <p><c>agent_config_opt() = {dir, agent_config_dir()} | {force_load, force_load()} | {verbosity, verbosity()}</c></p> <p>Defines specific config related options for the SNMP agent. </p> <p>For defaults see the options in <c>agent_config_opt()</c>.</p> </item> - <marker id="agent_config_dir"></marker> - <tag><c><![CDATA[agent_config_dir = dir() <mandatory>]]></c></tag> + <tag><marker id="agent_config_dir"></marker> + <c><![CDATA[agent_config_dir = dir() <mandatory>]]></c></tag> <item> <p>Defines where the SNMP agent configuration files are stored.</p> </item> - <marker id="agent_force_load"></marker> - <tag><c><![CDATA[force_load() = bool() <optional>]]></c></tag> + <tag><marker id="agent_force_load"></marker> + <c><![CDATA[force_load() = bool() <optional>]]></c></tag> <item> <p>If <c>true</c> the configuration files are re-read during start-up, and the contents of the configuration @@ -606,16 +608,16 @@ in so far as it will be converted to the new format if found. <marker id="manager_opts_and_types"></marker> <p>Manager specific config options and types:</p> <taglist> - <marker id="manager_server"></marker> - <tag><c><![CDATA[server() = [server_opt()] <optional>]]></c></tag> + <tag><marker id="manager_server"></marker> + <c><![CDATA[server() = [server_opt()] <optional>]]></c></tag> <item> <p><c>server_opt() = {timeout, server_timeout()} | {verbosity, verbosity()}</c></p> <p>Specifies the options for the manager server process.</p> <p>Default is <c>silence</c>.</p> </item> - <marker id="manager_server_timeout"></marker> - <tag><c><![CDATA[server_timeout() = integer() <optional>]]></c></tag> + <tag><marker id="manager_server_timeout"></marker> + <c><![CDATA[server_timeout() = integer() <optional>]]></c></tag> <item> <p>Asynchronous request cleanup time. For every requests, some info is stored internally, in order to be able to @@ -635,44 +637,44 @@ in so far as it will be converted to the new format if found. <p>Default is <c>30000</c>.</p> </item> - <marker id="manager_config"></marker> - <tag><c><![CDATA[manager_config() = [manager_config_opt()] <mandatory>]]></c></tag> + <tag><marker id="manager_config"></marker> + <c><![CDATA[manager_config() = [manager_config_opt()] <mandatory>]]></c></tag> <item> <p><c>manager_config_opt() = {dir, manager_config_dir()} | {db_dir, manager_db_dir()} | {db_init_error, db_init_error()} | {repair, manager_repair()} | {auto_save, manager_auto_save()} | {verbosity, verbosity()}</c></p> <p>Defines specific config related options for the SNMP manager. </p> <p>For defaults see the options in <c>manager_config_opt()</c>.</p> </item> - <marker id="manager_config_dir"></marker> - <tag><c><![CDATA[manager_config_dir = dir() <mandatory>]]></c></tag> + <tag><marker id="manager_config_dir"></marker> + <c><![CDATA[manager_config_dir = dir() <mandatory>]]></c></tag> <item> <p>Defines where the SNMP manager configuration files are stored.</p> </item> - <marker id="manager_config_db_dir"></marker> - <tag><c><![CDATA[manager_db_dir = dir() <mandatory>]]></c></tag> + <tag><marker id="manager_config_db_dir"></marker> + <c><![CDATA[manager_db_dir = dir() <mandatory>]]></c></tag> <item> <p>Defines where the SNMP manager store persistent data.</p> </item> - <marker id="manager_config_repair"></marker> - <tag><c><![CDATA[manager_repair() = false | true | force <optional>]]></c></tag> + <tag><marker id="manager_config_repair"></marker> + <c><![CDATA[manager_repair() = false | true | force <optional>]]></c></tag> <item> <p>Defines the repair option for the persistent database (if and how the table is repaired when opened). </p> <p>Default is <c>true</c>.</p> </item> - <marker id="manager_config_auto_save"></marker> - <tag><c><![CDATA[manager_auto_save() = integer() | infinity <optional>]]></c></tag> + <tag><marker id="manager_config_auto_save"></marker> + <c><![CDATA[manager_auto_save() = integer() | infinity <optional>]]></c></tag> <item> <p>The auto save interval. The table is flushed to disk whenever not accessed for this amount of time.</p> <p>Default is <c>5000</c>.</p> </item> - <marker id="manager_irb"></marker> - <tag><c><![CDATA[manager_irb() = auto | user | {user, integer()} <optional>]]></c></tag> + <tag><marker id="manager_irb"></marker> + <c><![CDATA[manager_irb() = auto | user | {user, integer()} <optional>]]></c></tag> <item> <p>This option defines how the manager will handle the sending of response (acknowledgment) to received inform-requests. </p> @@ -701,16 +703,16 @@ in so far as it will be converted to the new format if found. <p>Default is <c>auto</c>.</p> </item> - <marker id="manager_mibs"></marker> - <tag><c><![CDATA[manager_mibs() = [string()] <optional>]]></c></tag> + <tag><marker id="manager_mibs"></marker> + <c><![CDATA[manager_mibs() = [string()] <optional>]]></c></tag> <item> <p>Specifies a list of MIBs (including path) and defines which MIBs are initially loaded into the SNMP manager. </p> <p>Default is <c>[]</c>.</p> </item> - <marker id="manager_net_if"></marker> - <tag><c><![CDATA[manager_net_if() = [manager_net_if_opt()] <optional>]]></c></tag> + <tag><marker id="manager_net_if"></marker> + <c><![CDATA[manager_net_if() = [manager_net_if_opt()] <optional>]]></c></tag> <item> <p><c>manager_net_if_opt() = {module, manager_net_if_module()} | {verbosity, verbosity()} | @@ -720,8 +722,8 @@ in so far as it will be converted to the new format if found. <p>For defaults see the options in <c>manager_net_if_opt()</c>.</p> </item> - <marker id="manager_ni_opts"></marker> - <tag><c><![CDATA[manager_net_if_options() = [manager_net_if_option()] <optional>]]></c></tag> + <tag><marker id="manager_ni_opts"></marker> + <c><![CDATA[manager_net_if_options() = [manager_net_if_option()] <optional>]]></c></tag> <item> <p><c>manager_net_if_option() = {bind_to, bind_to()} | {sndbuf, sndbuf()} | @@ -734,8 +736,8 @@ in so far as it will be converted to the new format if found. <p>For defaults see the options in <c>manager_net_if_option()</c>.</p> </item> - <marker id="manager_ni_module"></marker> - <tag><c><![CDATA[manager_net_if_module() = atom() <optional>]]></c></tag> + <tag><marker id="manager_ni_module"></marker> + <c><![CDATA[manager_net_if_module() = atom() <optional>]]></c></tag> <item> <p>The module which handles the network interface part for the SNMP manager. It must implement the @@ -743,8 +745,8 @@ in so far as it will be converted to the new format if found. <p>Default is <c>snmpm_net_if</c>. </p> </item> - <marker id="manager_ni_filter_opts"></marker> - <tag><c><![CDATA[manager_net_if_filter_options() = [manager_net_if_filter_option()] <optional>]]></c></tag> + <tag><marker id="manager_ni_filter_opts"></marker> + <c><![CDATA[manager_net_if_filter_options() = [manager_net_if_filter_option()] <optional>]]></c></tag> <item> <p><c>manager_net_if_filter_option() = {module, manager_net_if_filter_module()}</c></p> <p>These options are actually specific to the used module. @@ -754,8 +756,8 @@ in so far as it will be converted to the new format if found. <c>manager_net_if_filter_option()</c>.</p> </item> - <marker id="manager_ni_filter_module"></marker> - <tag><c><![CDATA[manager_net_if_filter_module() = atom() <optional>]]></c></tag> + <tag><marker id="manager_ni_filter_module"></marker> + <c><![CDATA[manager_net_if_filter_module() = atom() <optional>]]></c></tag> <item> <p>Module which handles the network interface filter part for the SNMP manager. Must implement the @@ -763,16 +765,16 @@ in so far as it will be converted to the new format if found. <p>Default is <c>snmpm_net_if_filter</c>.</p> </item> - <marker id="manager_def_user_module"></marker> - <tag><c><![CDATA[def_user_module() = atom() <optional>]]></c></tag> + <tag><marker id="manager_def_user_module"></marker> + <c><![CDATA[def_user_module() = atom() <optional>]]></c></tag> <item> <p>The module implementing the default user. See the <seealso marker="snmpm_user">snmpm_user</seealso> behaviour.</p> <p>Default is <c>snmpm_user_default</c>.</p> </item> - <marker id="manager_def_user_data"></marker> - <tag><c><![CDATA[def_user_data() = term() <optional>]]></c></tag> + <tag><marker id="manager_def_user_data"></marker> + <c><![CDATA[def_user_data() = term() <optional>]]></c></tag> <item> <p>Data for the default user. Passed to the user when calling the callback functions.</p> @@ -783,8 +785,8 @@ in so far as it will be converted to the new format if found. <marker id="common_types"></marker> <p>Common config types:</p> <taglist> - <marker id="restart_type"></marker> - <tag><c>restart_type() = permanent | transient | temporary</c></tag> + <tag><marker id="restart_type"></marker> + <c>restart_type() = permanent | transient | temporary</c></tag> <item> <p>See <seealso marker="stdlib:supervisor#child_spec">supervisor</seealso> documentation for more info.</p> @@ -792,8 +794,8 @@ in so far as it will be converted to the new format if found. for the manager.</p> </item> - <marker id="db_init_error"></marker> - <tag><c>db_init_error() = terminate | create | create_db_and_dir</c></tag> + <tag><marker id="db_init_error"></marker> + <c>db_init_error() = terminate | create | create_db_and_dir</c></tag> <item> <p>Defines what to do if the agent is unable to open an existing database file. <c>terminate</c> means that the @@ -805,31 +807,31 @@ in so far as it will be converted to the new format if found. <p>Default is <c>terminate</c>.</p> </item> - <marker id="prio"></marker> - <tag><c><![CDATA[priority() = atom() <optional>]]></c></tag> + <tag><marker id="prio"></marker> + <c><![CDATA[priority() = atom() <optional>]]></c></tag> <item> <p>Defines the Erlang priority for all SNMP processes.</p> <p>Default is <c>normal</c>.</p> </item> - <marker id="versions"></marker> - <tag><c><![CDATA[versions() = [version()] <optional>]]></c></tag> + <tag><marker id="versions"></marker> + <c><![CDATA[versions() = [version()] <optional>]]></c></tag> <item> <p><c>version() = v1 | v2 | v3</c></p> <p>Which SNMP versions shall be accepted/used.</p> <p>Default is <c>[v1,v2,v3]</c>.</p> </item> - <marker id="verbosity"></marker> - <tag><c><![CDATA[verbosity() = silence | info | log | debug | trace <optional>]]></c></tag> + <tag><marker id="verbosity"></marker> + <c><![CDATA[verbosity() = silence | info | log | debug | trace <optional>]]></c></tag> <item> <p>Verbosity for a SNMP process. This specifies now much debug info is printed.</p> <p>Default is <c>silence</c>.</p> </item> - <marker id="bind_to"></marker> - <tag><c><![CDATA[bind_to() = bool() <optional>]]></c></tag> + <tag><marker id="bind_to"></marker> + <c><![CDATA[bind_to() = bool() <optional>]]></c></tag> <item> <p>If <c>true</c>, net_if binds to the IP address. If <c>false</c>, net_if listens on any IP address on the host @@ -837,8 +839,8 @@ in so far as it will be converted to the new format if found. <p>Default is <c>false</c>.</p> </item> - <marker id="no_reuse"></marker> - <tag><c><![CDATA[no_reuse() = bool() <optional>]]></c></tag> + <tag><marker id="no_reuse"></marker> + <c><![CDATA[no_reuse() = bool() <optional>]]></c></tag> <item> <p>If <c>true</c>, net_if does not specify that the IP and port address should be reusable. If <c>false</c>, @@ -846,30 +848,30 @@ in so far as it will be converted to the new format if found. <p>Default is <c>false</c>.</p> </item> - <marker id="recbuf"></marker> - <tag><c><![CDATA[recbuf() = integer() <optional>]]></c></tag> + <tag><marker id="recbuf"></marker> + <c><![CDATA[recbuf() = integer() <optional>]]></c></tag> <item> <p>Receive buffer size. </p> <p>Default value is defined by <c>gen_udp</c>.</p> </item> - <marker id="sndbuf"></marker> - <tag><c><![CDATA[sndbuf() = integer() <optional>]]></c></tag> + <tag><marker id="sndbuf"></marker> + <c><![CDATA[sndbuf() = integer() <optional>]]></c></tag> <item> <p>Send buffer size. </p> <p>Default value is defined by <c>gen_udp</c>.</p> </item> - <marker id="note_store"></marker> - <tag><c><![CDATA[note_store() = [note_store_opt()] <optional>]]></c></tag> + <tag><marker id="note_store"></marker> + <c><![CDATA[note_store() = [note_store_opt()] <optional>]]></c></tag> <item> <p><c>note_store_opt() = {timeout, note_store_timeout()} | {verbosity, verbosity()}</c></p> <p>Specifies the options for the SNMP note store.</p> <p>For defaults see the options in <c>note_store_opt()</c>.</p> </item> - <marker id="ns_timeout"></marker> - <tag><c><![CDATA[note_store_timeout() = integer() <optional>]]></c></tag> + <tag><marker id="ns_timeout"></marker> + <c><![CDATA[note_store_timeout() = integer() <optional>]]></c></tag> <item> <p>Note cleanup time. When storing a note in the note store, each note is given lifetime. Every <c>timeout</c> the note_store @@ -878,8 +880,8 @@ in so far as it will be converted to the new format if found. <p>Default is <c>30000</c>.</p> </item> - <marker id="audit_trail_log"></marker> - <tag><c><![CDATA[audit_trail_log() [audit_trail_log_opt()] <optional>]]></c></tag> + <tag><marker id="audit_trail_log"></marker> + <c><![CDATA[audit_trail_log() [audit_trail_log_opt()] <optional>]]></c></tag> <item> <p><c>audit_trail_log_opt() = {type, atl_type()} | {dir, atl_dir()} | {size, atl_size()} | {repair, atl_repair()} | {seqno, atl_seqno()}</c></p> <p>If present, this option specifies the options for the @@ -889,8 +891,8 @@ in so far as it will be converted to the new format if found. <p>If not present, audit trail logging is not used.</p> </item> - <marker id="atl_type"></marker> - <tag><c><![CDATA[atl_type() = read | write | read_write <optional>]]></c></tag> + <tag><marker id="atl_type"></marker> + <c><![CDATA[atl_type() = read | write | read_write <optional>]]></c></tag> <item> <p>Specifies what type of an audit trail log should be used. The effect of the type is actually different for the the agent @@ -911,16 +913,16 @@ in so far as it will be converted to the new format if found. <p>Default is <c>read_write</c>.</p> </item> - <marker id="atl_dir"></marker> - <tag><c><![CDATA[atl_dir = dir() <mandatory>]]></c></tag> + <tag><marker id="atl_dir"></marker> + <c><![CDATA[atl_dir = dir() <mandatory>]]></c></tag> <item> <p>Specifies where the audit trail log should be stored.</p> <p>If <c>audit_trail_log</c> specifies that logging should take place, this parameter <em>must</em> be defined.</p> </item> - <marker id="atl_size"></marker> - <tag><c><![CDATA[atl_size() = {integer(), integer()} <mandatory>]]></c></tag> + <tag><marker id="atl_size"></marker> + <c><![CDATA[atl_size() = {integer(), integer()} <mandatory>]]></c></tag> <item> <p>Specifies the size of the audit trail log. This parameter is sent to <c>disk_log</c>. </p> @@ -928,8 +930,8 @@ in so far as it will be converted to the new format if found. take place, this parameter <em>must</em> be defined.</p> </item> - <marker id="atl_repair"></marker> - <tag><c><![CDATA[atl_repair() = true | false | truncate | snmp_repair <optional>]]></c></tag> + <tag><marker id="atl_repair"></marker> + <c><![CDATA[atl_repair() = true | false | truncate | snmp_repair <optional>]]></c></tag> <item> <p>Specifies if and how the audit trail log shall be repaired when opened. Unless this parameter has the value <c>snmp_repair</c> @@ -941,8 +943,8 @@ in so far as it will be converted to the new format if found. <p>Default is <c>true</c>.</p> </item> - <marker id="atl_seqno"></marker> - <tag><c><![CDATA[atl_seqno() = true | false <optional>]]></c></tag> + <tag><marker id="atl_seqno"></marker> + <c><![CDATA[atl_seqno() = true | false <optional>]]></c></tag> <item> <p>Specifies if the audit trail log entries will be (sequence) numbered or not. The range of the sequence numbers are according diff --git a/lib/snmp/doc/src/snmp_manager_netif.xml b/lib/snmp/doc/src/snmp_manager_netif.xml index 8454d03b17..98d4e7fd96 100644 --- a/lib/snmp/doc/src/snmp_manager_netif.xml +++ b/lib/snmp/doc/src/snmp_manager_netif.xml @@ -75,8 +75,7 @@ <p>In this section a <c>Domain</c> field is the transport domain i.e one of <c>transportDomainUdpIpv4</c> or <c>transportDomainUdpIpv6</c>, and an <c>Addr</c> field is an - <c>{<seealso marker="kernel:inet#type-ip_address">IpAddr</seealso>, - IpPort}</c> tuple.</p> + <c>{</c><seealso marker="kernel:inet#type-ip_address"><c>IpAddr</c></seealso><c>,IpPort}</c> tuple.</p> <p>Net if must send the following message when it receives an SNMP PDU from the network that is aimed for the MasterAgent: diff --git a/lib/snmp/doc/src/snmpa.xml b/lib/snmp/doc/src/snmpa.xml index f205af6e88..c84eeec524 100644 --- a/lib/snmp/doc/src/snmpa.xml +++ b/lib/snmp/doc/src/snmpa.xml @@ -622,12 +622,12 @@ notification_delivery_info() = #snmpa_notification_delivery_info{} <p>Converts an Audit Trail Log to a readable format and prints it on stdio. <c>LogName</c> defaults to "snmpa_log". - <c>LogFile</c> defaults to "snmpa.log". + <c>LogFile</c> defaults to "snmpa.log".</p> <p>The <c>Block</c> option indicates if the log should be blocked during conversion. This could be usefull when converting large logs (when otherwise the log could wrap during conversion). Defaults to <c>true</c>. </p> - See <seealso marker="snmp#log_to_io">snmp:log_to_io</seealso> + <p>See <seealso marker="snmp#log_to_io">snmp:log_to_io</seealso> for more info.</p> <marker id="change_log_size"></marker> diff --git a/lib/snmp/doc/src/snmpm.xml b/lib/snmp/doc/src/snmpm.xml index b14c0e6afd..ab288fd020 100644 --- a/lib/snmp/doc/src/snmpm.xml +++ b/lib/snmp/doc/src/snmpm.xml @@ -1241,12 +1241,12 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1 <p>Converts an Audit Trail Log to a readable text file. <c>OutFile</c> defaults to "./snmpm_log.txt". <c>LogName</c> defaults to "snmpm_log". - <c>LogFile</c> defaults to "snmpm.log". + <c>LogFile</c> defaults to "snmpm.log".</p> <p>The <c>Block</c> argument indicates if the log should be blocked during conversion. This could be usefull when converting large logs (when otherwise the log could wrap during conversion). Defaults to <c>true</c>. </p> - See <seealso marker="snmp#log_to_txt">snmp:log_to_txt</seealso> + <p>See <seealso marker="snmp#log_to_txt">snmp:log_to_txt</seealso> for more info.</p> <marker id="log_to_io"></marker> @@ -1280,12 +1280,12 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1 <p>Converts an Audit Trail Log to a readable format and prints it on stdio. <c>LogName</c> defaults to "snmpm_log". - <c>LogFile</c> defaults to "snmpm.log". + <c>LogFile</c> defaults to "snmpm.log".</p> <p>The <c>Block</c> argument indicates if the log should be blocked during conversion. This could be usefull when converting large logs (when otherwise the log could wrap during conversion). Defaults to <c>true</c>. </p> - See <seealso marker="snmp#log_to_io">snmp:log_to_io</seealso> + <p>See <seealso marker="snmp#log_to_io">snmp:log_to_io</seealso> for more info.</p> <marker id="change_log_size"></marker> diff --git a/lib/ssh/doc/src/notes.xml b/lib/ssh/doc/src/notes.xml index bb111c8e0e..010b1b15c7 100644 --- a/lib/ssh/doc/src/notes.xml +++ b/lib/ssh/doc/src/notes.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2004</year><year>2014</year> + <year>2004</year><year>2015</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -30,6 +30,22 @@ <file>notes.xml</file> </header> +<section><title>Ssh 4.1.3</title> + + <section><title>Known Bugs and Problems</title> + <list> + <item> + <p> + SSH_MSG_KEX_DH_GEX_REQUEST_OLD implemented to make PuTTY + work with erl server.</p> + <p> + Own Id: OTP-13140</p> + </item> + </list> + </section> + +</section> + <section><title>Ssh 4.1.2</title> <section><title>Fixed Bugs and Malfunctions</title> @@ -216,9 +232,9 @@ <p> Thanks to Simon Cornish</p> <p> - Own Id: OTP-12760 Aux Id: <a + Own Id: OTP-12760 Aux Id: <url href="https://github.com/erlang/otp/pull/715">pull req - 715</a> </p> + 715</url> </p> </item> <item> <p> @@ -384,13 +400,13 @@ </item> <item> <p> - Made Codenomicon Defensics test suite pass: <list> + Made Codenomicon Defensics test suite pass:</p> <list> <item>limit number of algorithms in kexinit message</item> <item>check 'e' and 'f' parameters in kexdh</item> <item>implement 'keyboard-interactive' user authentication on server side</item> <item> return plain text message to bad version exchange message</item> - </list></p> + </list> <p> Own Id: OTP-12784</p> </item> diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml index 0e5a0706f5..b3f850fc38 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -32,34 +32,10 @@ <modulesummary>Main API of the ssh application</modulesummary> <description> <p>Interface module for the <c>ssh</c> application.</p> + <p>See <seealso marker="ssh:SSH_app#supported">ssh(6)</seealso> for details of supported version, + algorithms and unicode support.</p> </description> - <section> - <title>SSH</title> - <marker id="supported"/> - <list type="bulleted"> - <item>For application dependencies see <seealso marker="SSH_app"> ssh(6)</seealso> </item> - <item>Supported SSH version is 2.0.</item> - <item>Supported public key algorithms: ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, ssh-rsa and ssh-dss.</item> - <item>Supported MAC algorithms: hmac-sha2-256, hmac-sha2-512 and hmac-sha1.</item> - <item>Supported encryption algorithms: aes256-ctr, aes192-ctr, aes128-ctr, aes128-cb and 3des-cbc.</item> - <item>Supported key exchange algorithms: ecdh-sha2-nistp256, ecdh-sha2-nistp384, ecdh-sha2-nistp521, diffie-hellman-group14-sha1, diffie-hellman-group-exchange-sha1, diffie-hellman-group-exchange-sha256 and diffie-hellman-group1-sha1</item> - <item>Supported compression algorithms: none, [email protected] and zlib</item> - <item>Supports unicode filenames if the emulator and the underlaying OS support it. - See section DESCRIPTION in the - <seealso marker="kernel:file">file</seealso> manual page in <c>kernel</c> - for information about this subject.</item> - <item>Supports unicode in shell and CLI.</item> - </list> - <p>The actual set of algorithms can vary depending on which OpenSSL crypto library that is installed on the machine. - For the list on a particular installation, use the command <seealso marker="#default_algorithms/0">default_algorithms/0</seealso>. - The user may override the default algorithm configuration both on the server side and the client side. - See the option preferred_algorithms in the <seealso marker="#daemon/1">daemon</seealso> and - <seealso marker="#connect/3">connect</seealso> functions. -</p> - - </section> - <section> <title>OPTIONS</title> <p>The exact behaviour of some functions can be adjusted with the use of options which are documented together @@ -109,6 +85,15 @@ <item><p><c>atom()</c> - Name of the Erlang module implementing the subsystem using the <c>ssh_channel</c> behavior, see <seealso marker="ssh_channel">ssh_channel(3)</seealso></p></item> + <tag><c>key_cb() =</c></tag> + <item> + <p><c>atom() | {atom(), list()}</c></p> + <p><c>atom()</c> - Name of the erlang module implementing the behaviours + <seealso marker="ssh_client_key_api">ssh_client_key_api</seealso> or + <seealso marker="ssh_client_key_api">ssh_client_key_api</seealso> as the + case maybe.</p> + <p><c>list()</c> - List of options that can be passed to the callback module.</p> + </item> <tag><c>channel_init_args() =</c></tag> <item><p><c>list()</c></p></item> @@ -221,26 +206,25 @@ <tag><c><![CDATA[{public_key_alg, 'ssh-rsa' | 'ssh-dss'}]]></c></tag> <item> <note> - <p>This option is kept for compatibility. It is ignored if the <c>preferred_algorithms</c> - option is used. The equivalence of <c>{public_key_alg,'ssh-dss'}</c> is - <c>{preferred_algorithms, [{public_key,['ssh-dss','ssh-rsa']}]}</c>.</p> + <p>This option will be removed in OTP 20, but is kept for compatibility. It is ignored if + the preferred <c>pref_public_key_algs</c> option is used.</p> </note> <p>Sets the preferred public key algorithm to use for user authentication. If the preferred algorithm fails, - the other algorithm is tried. The default is - to try <c><![CDATA['ssh-rsa']]></c> first.</p> + the other algorithm is tried. If <c>{public_key_alg, 'ssh-rsa'}</c> is set, it is translated + to <c>{pref_public_key_algs, ['ssh-rsa','ssh-dss']}</c>. If it is + <c>{public_key_alg, 'ssh-dss'}</c>, it is translated + to <c>{pref_public_key_algs, ['ssh-dss','ssh-rsa']}</c>. + </p> </item> <tag><c><![CDATA[{pref_public_key_algs, list()}]]></c></tag> <item> - <note> - <p>This option is kept for compatibility. It is ignored if the <c>preferred_algorithms</c> - option is used. The equivalence of <c>{pref_public_key_algs,['ssh-dss']}</c> is - <c>{preferred_algorithms, [{public_key,['ssh-dss']}]}</c>.</p> - </note> - <p>List of public key algorithms to try to use. - <c>'ssh-rsa'</c> and <c>'ssh-dss'</c> are available. - Overrides <c><![CDATA[{public_key_alg, 'ssh-rsa' | 'ssh-dss'}]]></c></p> + <p>List of user (client) public key algorithms to try to use.</p> + <p>The default value is + <c><![CDATA[['ssh-rsa','ssh-dss','ecdsa-sha2-nistp256','ecdsa-sha2-nistp384','ecdsa-sha2-nistp521'] ]]></c> + </p> + <p>If there is no public key of a specified type available, the corresponding entry is ignored.</p> </item> <tag><c><![CDATA[{preferred_algorithms, algs_list()}]]></c></tag> @@ -248,6 +232,7 @@ <p>List of algorithms to use in the algorithm negotiation. The default <c>algs_list()</c> can be obtained from <seealso marker="#default_algorithms/0">default_algorithms/0</seealso>. </p> + <p>If an alg_entry() is missing in the algs_list(), the default value is used for that entry.</p> <p>Here is an example of this option:</p> <code> {preferred_algorithms, @@ -258,9 +243,9 @@ {compression,[none,zlib]} } </code> - <p>The example specifies different algorithms in the two directions (client2server and server2client), for cipher but specifies the same -algorithms for mac and compression in both directions. The kex (key exchange) and public key algorithms are set to their default values, -kex is implicit but public_key is set explicitly.</p> + <p>The example specifies different algorithms in the two directions (client2server and server2client), + for cipher but specifies the same algorithms for mac and compression in both directions. + The kex (key exchange) is implicit but public_key is set explicitly.</p> <warning> <p>Changing the values can make a connection less secure. Do not change unless you @@ -296,11 +281,13 @@ kex is implicit but public_key is set explicitly.</p> password, if the password authentication method is attempted.</p> </item> - <tag><c><![CDATA[{key_cb, atom()}]]></c></tag> + <tag><c><![CDATA[{key_cb, key_cb()}]]></c></tag> <item> - <p>Module implementing the behaviour - <seealso marker="ssh_client_key_api">ssh_client_key_api</seealso>. - Can be used to customize the handling of public keys. + <p>Module implementing the behaviour <seealso + marker="ssh_client_key_api">ssh_client_key_api</seealso>. Can be used to + customize the handling of public keys. If callback options are provided + along with the module name, they are made available to the callback + module via the options passed to it under the key 'key_cb_private'. </p> </item> <tag><c><![CDATA[{quiet_mode, atom() = boolean()}]]></c></tag> @@ -464,6 +451,7 @@ kex is implicit but public_key is set explicitly.</p> <p>List of algorithms to use in the algorithm negotiation. The default <c>algs_list()</c> can be obtained from <seealso marker="#default_algorithms/0">default_algorithms/0</seealso>. </p> + <p>If an alg_entry() is missing in the algs_list(), the default value is used for that entry.</p> <p>Here is an example of this option:</p> <code> {preferred_algorithms, @@ -474,9 +462,9 @@ kex is implicit but public_key is set explicitly.</p> {compression,[none,zlib]} } </code> - <p>The example specifies different algorithms in the two directions (client2server and server2client), for cipher but specifies the same -algorithms for mac and compression in both directions. The kex (key exchange) and public key algorithms are set to their default values, -kex is implicit but public_key is set explicitly.</p> + <p>The example specifies different algorithms in the two directions (client2server and server2client), + for cipher but specifies the same algorithms for mac and compression in both directions. + The kex (key exchange) is implicit but public_key is set explicitly.</p> <warning> <p>Changing the values can make a connection less secure. Do not change unless you @@ -631,11 +619,13 @@ kex is implicit but public_key is set explicitly.</p> </p> </item> - <tag><c><![CDATA[{key_cb, atom()}]]></c></tag> + <tag><c><![CDATA[{key_cb, key_cb()}]]></c></tag> <item> - <p>Module implementing the behaviour - <seealso marker="ssh_server_key_api">ssh_server_key_api</seealso>. - Can be used to customize the handling of public keys. + <p>Module implementing the behaviour <seealso + marker="ssh_server_key_api">ssh_server_key_api</seealso>. Can be used to + customize the handling of public keys. If callback options are provided + along with the module name, they are made available to the callback + module via the options passed to it under the key 'key_cb_private'. </p> </item> diff --git a/lib/ssh/doc/src/ssh_app.xml b/lib/ssh/doc/src/ssh_app.xml index 4c85585820..79dd1e210e 100644 --- a/lib/ssh/doc/src/ssh_app.xml +++ b/lib/ssh/doc/src/ssh_app.xml @@ -41,15 +41,18 @@ <section> <title>DEPENDENCIES</title> - <p>The <c>ssh</c> application uses the applications <c>public_key</c> and - <c>crypto</c> to handle public keys and encryption. Hence, these + <p>The <c>ssh</c> application uses the applications + <seealso marker="public_key:public_key">public_key</seealso> and + <seealso marker="crypto:crypto">crypto</seealso> + to handle public keys and encryption. Hence, these applications must be loaded for the <c>ssh</c> application to work. In an embedded environment this means that they must be started with - <c>application:start/[1,2]</c> before the <c>ssh</c> application is started. + <seealso marker="kernel:application#start/1">application:start/1,2</seealso> before the + <c>ssh</c> application is started. </p> </section> - <section> + <section> <title>CONFIGURATION</title> <p>The <c>ssh</c> application does not have an application- @@ -62,10 +65,13 @@ <item><c>authorized_keys2</c></item> <item><c>id_dsa</c></item> <item><c>id_rsa</c></item> + <item><c>id_ecdsa</c></item> <item><c>ssh_host_dsa_key</c></item> <item><c>ssh_host_rsa_key</c></item> + <item><c>ssh_host_ecdsa_key</c></item> </list> <p>By default, <c>ssh</c> looks for <c>id_dsa</c>, <c>id_rsa</c>, + <c>id_ecdsa_key</c>, <c>known_hosts</c>, and <c>authorized_keys</c> in ~/.ssh, and for the host key files in <c>/etc/ssh</c>. These locations can be changed by the options <c>user_dir</c> and <c>system_dir</c>. @@ -79,7 +85,7 @@ </section> <section> <title>Public Keys</title> - <p><c>id_dsa</c> and <c>id_rsa</c> are the users private key files. + <p><c>id_dsa</c>, <c>id_rsa</c> and <c>id_ecdsa</c> are the users private key files. Notice that the public key is part of the private key so the <c>ssh</c> application does not use the <c>id_<*>.pub</c> files. These are for the user's convenience when it is needed to convey the user's @@ -104,8 +110,8 @@ <section> <title>Host Keys</title> <p>RSA and DSA host keys are supported and are - expected to be found in files named <c>ssh_host_rsa_key</c> and - <c>ssh_host_dsa_key</c>. + expected to be found in files named <c>ssh_host_rsa_key</c>, + <c>ssh_host_dsa_key</c> and <c>ssh_host_ecdsa_key</c>. </p> </section> <section> @@ -114,6 +120,197 @@ </section> <section> + <marker id="supported"/> + <title>SUPPORTED SPECIFICATIONS AND STANDARDS</title> + <p>The supported SSH version is 2.0.</p> + </section> + <section> + <title>Algorithms</title> + <p>The actual set of algorithms may vary depending on which OpenSSL crypto library that is installed on the machine. + For the list on a particular installation, use the command + <seealso marker="ssh:ssh#default_algorithms/0">ssh:default_algorithms/0</seealso>. + The user may override the default algorithm configuration both on the server side and the client side. + See the option <c>preferred_algorithms</c> in the <seealso marker="ssh:ssh#daemon/1">ssh:daemon/1,2,3</seealso> and + <seealso marker="ssh:ssh#connect/3">ssh:connect/3,4</seealso> functions. + </p> + + <p>Supported algorithms are:</p> + + <taglist> + <tag>Key exchange algorithms</tag> + <item> + <list type="bulleted"> + <item>ecdh-sha2-nistp256</item> + <item>ecdh-sha2-nistp384</item> + <item>ecdh-sha2-nistp521</item> + <item>diffie-hellman-group-exchange-sha1</item> + <item>diffie-hellman-group-exchange-sha256</item> + <item>diffie-hellman-group14-sha1</item> + <item>diffie-hellman-group1-sha1</item> + </list> + </item> + + <tag>Public key algorithms</tag> + <item> + <list type="bulleted"> + <item>ecdsa-sha2-nistp256</item> + <item>ecdsa-sha2-nistp384</item> + <item>ecdsa-sha2-nistp521</item> + <item>ssh-rsa</item> + <item>ssh-dss</item> + </list> + </item> + + <tag>MAC algorithms</tag> + <item> + <list type="bulleted"> + <item>hmac-sha2-256</item> + <item>hmac-sha2-512</item> + <item>hmac-sha1</item> + </list> + </item> + + <tag>Encryption algorithms (ciphers)</tag> + <item> + <list type="bulleted"> + <item>[email protected] (AEAD_AES_128_GCM)</item> + <item>[email protected] (AEAD_AES_256_GCM)</item> + <item>aes128-ctr</item> + <item>aes192-ctr</item> + <item>aes256-ctr</item> + <item>aes128-cbc</item> + <item>3des-cbc</item> + </list> + <p>Following the internet de-facto standard, the cipher and mac algorithm AEAD_AES_128_GCM is selected when the + cipher [email protected] is negotiated. The cipher and mac algorithm AEAD_AES_256_GCM is selected when the + cipher [email protected] is negotiated. + </p> + <p>See the text at the description of <seealso marker="#rfc5647_note">the rfc 5647 further down</seealso> + for more information. + </p> + </item> + + <tag>Compression algorithms</tag> + <item> + <list type="bulleted"> + <item>none</item> + <item>[email protected]</item> + <item>zlib</item> + </list> + </item> + </taglist> + </section> + <section> + <title>Unicode support</title> + <p>Unicode filenames are supported if the emulator and the underlaying OS support it. See section DESCRIPTION in the + <seealso marker="kernel:file">file</seealso> manual page in <c>kernel</c> for information about this subject. + </p> + <p>The shell and the cli both support unicode. + </p> + </section> + + <section> + <title>Rfcs</title> + <p>The following rfc:s are supported:</p> + <list type="bulleted"> + <item><url href="https://tools.ietf.org/html/rfc4251">RFC 4251</url>, The Secure Shell (SSH) Protocol Architecture. + <p>Except + <list type="bulleted"> + <item>9.4.6 Host-Based Authentication</item> + <item>9.5.2 Proxy Forwarding</item> + <item>9.5.3 X11 Forwarding</item> + </list> + </p> + </item> + + <item><url href="https://tools.ietf.org/html/rfc4252">RFC 4252</url>, The Secure Shell (SSH) Authentication Protocol. + <p>Except + <list type="bulleted"> + <item>9. Host-Based Authentication: "hostbased"</item> + </list> + </p> + </item> + + <item><url href="https://tools.ietf.org/html/rfc4253">RFC 4253</url>, The Secure Shell (SSH) Transport Layer Protocol. + <p></p> + </item> + + <item><url href="https://tools.ietf.org/html/rfc4254">RFC 4254</url>, The Secure Shell (SSH) Connection Protocol. + <p>Except + <list type="bulleted"> + <item>6.3. X11 Forwarding</item> + <item>7. TCP/IP Port Forwarding</item> + </list> + </p> + </item> + + <item><url href="https://tools.ietf.org/html/rfc4256">RFC 4256</url>, Generic Message Exchange Authentication for + the Secure Shell Protocol (SSH). + <p>Except + <list type="bulleted"> + <item><c>num-prompts > 1</c></item> + <item>password changing</item> + <item>other identification methods than userid-password</item> + </list> + </p> + </item> + + <item><url href="https://tools.ietf.org/html/rfc4419">RFC 4419</url>, Diffie-Hellman Group Exchange for + the Secure Shell (SSH) Transport Layer Protocol. + <p></p> + </item> + + <item><url href="https://tools.ietf.org/html/rfc4716">RFC 4716</url>, The Secure Shell (SSH) Public Key File Format. + <p></p> + </item> + + <item><url href="https://tools.ietf.org/html/rfc5647">RFC 5647</url>, AES Galois Counter Mode for + the Secure Shell Transport Layer Protocol. + <p><marker id="rfc5647_note"/>There is an ambiguity in the synchronized selection of cipher and mac algorithm. + This is resolved by OpenSSH in the ciphers [email protected] and [email protected] which are implemented. + If the explicit ciphers and macs AEAD_AES_128_GCM or AEAD_AES_256_GCM are needed, + they could be enabled with the option preferred_algorithms. + <warning> + If the client or the server is not Erlang/OTP, it is the users responsibility to check that + other implementation has the same interpretation of AEAD_AES_*_GCM as the Erlang/OTP SSH before + enabling them. The aes*[email protected] variants are always safe to use since they lack the + ambiguity. + </warning> + </p> + <p>The second paragraph in section 5.1 is resolved as: + <list type="ordered"> + <item>If the negotiated cipher is AEAD_AES_128_GCM, the mac algorithm is set to AEAD_AES_128_GCM.</item> + <item>If the negotiated cipher is AEAD_AES_256_GCM, the mac algorithm is set to AEAD_AES_256_GCM.</item> + <item>If the mac algorithm is AEAD_AES_128_GCM, the cipher is set to AEAD_AES_128_GCM.</item> + <item>If the mac algorithm is AEAD_AES_256_GCM, the cipher is set to AEAD_AES_256_GCM.</item> + </list> + The first rule that matches when read in order from the top is applied + </p> + </item> + + <item><url href="https://tools.ietf.org/html/rfc5656">RFC 5656</url>, Elliptic Curve Algorithm Integration in + the Secure Shell Transport Layer. + <p>Except + <list type="bulleted"> + <item>5. ECMQV Key Exchange</item> + <item>6.4. ECMQV Key Exchange and Verification Method Name</item> + <item>7.2. ECMQV Message Numbers</item> + <item>10.2. Recommended Curves</item> + </list> + </p> + </item> + + <item><url href="https://tools.ietf.org/html/rfc6668">RFC 6668</url>, SHA-2 Data Integrity Verification for + the Secure Shell (SSH) Transport Layer Protocol + <p>Comment: Defines hmac-sha2-256 and hmac-sha2-512 + </p> + </item> + + </list> + + </section> + + <section> <title>SEE ALSO</title> <p><seealso marker="kernel:application">application(3)</seealso></p> </section> diff --git a/lib/ssh/doc/src/ssh_connection.xml b/lib/ssh/doc/src/ssh_connection.xml index 9a7bb09b12..064a623eb6 100644 --- a/lib/ssh/doc/src/ssh_connection.xml +++ b/lib/ssh/doc/src/ssh_connection.xml @@ -373,6 +373,9 @@ <desc> <p>Is to be called by client- and server-channel processes to send data to each other. </p> + <p>The function <seealso marker="ssh:ssh_connection#subsystem/4">subsystem/4</seealso> and subsequent + calls of <c>send/3,4,5</c> must be executed in the same process. + </p> </desc> </func> @@ -454,6 +457,9 @@ <p>Is to be called by a client-channel process for requesting to execute a predefined subsystem on the server. </p> + <p>The function <c>subsystem/4</c> and subsequent calls of + <seealso marker="ssh:ssh_connection#send/3">send/3,4,5</seealso> must be executed in the same process. + </p> </desc> </func> diff --git a/lib/ssh/doc/src/using_ssh.xml b/lib/ssh/doc/src/using_ssh.xml index 91185a0f6e..6826f20fb3 100644 --- a/lib/ssh/doc/src/using_ssh.xml +++ b/lib/ssh/doc/src/using_ssh.xml @@ -234,7 +234,7 @@ <title>SFTP Client with TAR Compression and Encryption</title> <p>Example of writing and then reading a tar file follows:</p> - <code type="erlang"> + <code type="erl"> {ok,HandleWrite} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [write]), ok = erl_tar:add(HandleWrite, .... ), ok = erl_tar:add(HandleWrite, .... ), @@ -249,10 +249,10 @@ </code> <p>The previous write and read example can be extended with encryption and decryption as follows:</p> - <code type="erlang"> + <code type="erl"> %% First three parameters depending on which crypto type we select: Key = <<"This is a 256 bit key. abcdefghi">>, -Ivec0 = crypto:rand_bytes(16), +Ivec0 = crypto:strong_rand_bytes(16), DataSize = 1024, % DataSize rem 16 = 0 for aes_cbc %% Initialization of the CryptoState, in this case it is the Ivector. diff --git a/lib/ssh/doc/standard/draft-ietf-secsh-architecture-15.2.ps b/lib/ssh/doc/standard/draft-ietf-secsh-architecture-15.2.ps deleted file mode 100644 index d766a933b4..0000000000 --- a/lib/ssh/doc/standard/draft-ietf-secsh-architecture-15.2.ps +++ /dev/null @@ -1,3315 +0,0 @@ -%!PS-Adobe-3.0 -%%BoundingBox: 75 0 595 747 -%%Title: Enscript Output -%%For: Magnus Thoang -%%Creator: GNU enscript 1.6.1 -%%CreationDate: Fri Oct 31 13:31:26 2003 -%%Orientation: Portrait -%%Pages: 15 0 -%%DocumentMedia: A4 595 842 0 () () -%%DocumentNeededResources: (atend) -%%EndComments -%%BeginProlog -%%BeginProcSet: PStoPS 1 15 -userdict begin -[/showpage/erasepage/copypage]{dup where{pop dup load - type/operatortype eq{1 array cvx dup 0 3 index cvx put - bind def}{pop}ifelse}{pop}ifelse}forall -[/letter/legal/executivepage/a4/a4small/b5/com10envelope - /monarchenvelope/c5envelope/dlenvelope/lettersmall/note - /folio/quarto/a5]{dup where{dup wcheck{exch{}put} - {pop{}def}ifelse}{pop}ifelse}forall -/setpagedevice {pop}bind 1 index where{dup wcheck{3 1 roll put} - {pop def}ifelse}{def}ifelse -/PStoPSmatrix matrix currentmatrix def -/PStoPSxform matrix def/PStoPSclip{clippath}def -/defaultmatrix{PStoPSmatrix exch PStoPSxform exch concatmatrix}bind def -/initmatrix{matrix defaultmatrix setmatrix}bind def -/initclip[{matrix currentmatrix PStoPSmatrix setmatrix - [{currentpoint}stopped{$error/newerror false put{newpath}} - {/newpath cvx 3 1 roll/moveto cvx 4 array astore cvx}ifelse] - {[/newpath cvx{/moveto cvx}{/lineto cvx} - {/curveto cvx}{/closepath cvx}pathforall]cvx exch pop} - stopped{$error/errorname get/invalidaccess eq{cleartomark - $error/newerror false put cvx exec}{stop}ifelse}if}bind aload pop - /initclip dup load dup type dup/operatortype eq{pop exch pop} - {dup/arraytype eq exch/packedarraytype eq or - {dup xcheck{exch pop aload pop}{pop cvx}ifelse} - {pop cvx}ifelse}ifelse - {newpath PStoPSclip clip newpath exec setmatrix} bind aload pop]cvx def -/initgraphics{initmatrix newpath initclip 1 setlinewidth - 0 setlinecap 0 setlinejoin []0 setdash 0 setgray - 10 setmiterlimit}bind def -end -%%EndProcSet -%%BeginResource: procset Enscript-Prolog 1.6 1 -% -% Procedures. -% - -/_S { % save current state - /_s save def -} def -/_R { % restore from saved state - _s restore -} def - -/S { % showpage protecting gstate - gsave - showpage - grestore -} bind def - -/MF { % fontname newfontname -> - make a new encoded font - /newfontname exch def - /fontname exch def - - /fontdict fontname findfont def - /newfont fontdict maxlength dict def - - fontdict { - exch - dup /FID eq { - % skip FID pair - pop pop - } { - % copy to the new font dictionary - exch newfont 3 1 roll put - } ifelse - } forall - - newfont /FontName newfontname put - - % insert only valid encoding vectors - encoding_vector length 256 eq { - newfont /Encoding encoding_vector put - } if - - newfontname newfont definefont pop -} def - -/SF { % fontname width height -> - set a new font - /height exch def - /width exch def - - findfont - [width 0 0 height 0 0] makefont setfont -} def - -/SUF { % fontname width height -> - set a new user font - /height exch def - /width exch def - - /F-gs-user-font MF - /F-gs-user-font width height SF -} def - -/M {moveto} bind def -/s {show} bind def - -/Box { % x y w h -> - define box path - /d_h exch def /d_w exch def /d_y exch def /d_x exch def - d_x d_y moveto - d_w 0 rlineto - 0 d_h rlineto - d_w neg 0 rlineto - closepath -} def - -/bgs { % x y height blskip gray str -> - show string with bg color - /str exch def - /gray exch def - /blskip exch def - /height exch def - /y exch def - /x exch def - - gsave - x y blskip sub str stringwidth pop height Box - gray setgray - fill - grestore - x y M str s -} def - -% Highlight bars. -/highlight_bars { % nlines lineheight output_y_margin gray -> - - gsave - setgray - /ymarg exch def - /lineheight exch def - /nlines exch def - - % This 2 is just a magic number to sync highlight lines to text. - 0 d_header_y ymarg sub 2 sub translate - - /cw d_output_w cols div def - /nrows d_output_h ymarg 2 mul sub lineheight div cvi def - - % for each column - 0 1 cols 1 sub { - cw mul /xp exch def - - % for each rows - 0 1 nrows 1 sub { - /rn exch def - rn lineheight mul neg /yp exch def - rn nlines idiv 2 mod 0 eq { - % Draw highlight bar. 4 is just a magic indentation. - xp 4 add yp cw 8 sub lineheight neg Box fill - } if - } for - } for - - grestore -} def - -% Line highlight bar. -/line_highlight { % x y width height gray -> - - gsave - /gray exch def - Box gray setgray fill - grestore -} def - -% Column separator lines. -/column_lines { - gsave - .1 setlinewidth - 0 d_footer_h translate - /cw d_output_w cols div def - 1 1 cols 1 sub { - cw mul 0 moveto - 0 d_output_h rlineto stroke - } for - grestore -} def - -% Column borders. -/column_borders { - gsave - .1 setlinewidth - 0 d_footer_h moveto - 0 d_output_h rlineto - d_output_w 0 rlineto - 0 d_output_h neg rlineto - closepath stroke - grestore -} def - -% Do the actual underlay drawing -/draw_underlay { - ul_style 0 eq { - ul_str true charpath stroke - } { - ul_str show - } ifelse -} def - -% Underlay -/underlay { % - -> - - gsave - 0 d_page_h translate - d_page_h neg d_page_w atan rotate - - ul_gray setgray - ul_font setfont - /dw d_page_h dup mul d_page_w dup mul add sqrt def - ul_str stringwidth pop dw exch sub 2 div ul_h_ptsize -2 div moveto - draw_underlay - grestore -} def - -/user_underlay { % - -> - - gsave - ul_x ul_y translate - ul_angle rotate - ul_gray setgray - ul_font setfont - 0 0 ul_h_ptsize 2 div sub moveto - draw_underlay - grestore -} def - -% Page prefeed -/page_prefeed { % bool -> - - statusdict /prefeed known { - statusdict exch /prefeed exch put - } { - pop - } ifelse -} def - -% Wrapped line markers -/wrapped_line_mark { % x y charwith charheight type -> - - /type exch def - /h exch def - /w exch def - /y exch def - /x exch def - - type 2 eq { - % Black boxes (like TeX does) - gsave - 0 setlinewidth - x w 4 div add y M - 0 h rlineto w 2 div 0 rlineto 0 h neg rlineto - closepath fill - grestore - } { - type 3 eq { - % Small arrows - gsave - .2 setlinewidth - x w 2 div add y h 2 div add M - w 4 div 0 rlineto - x w 4 div add y lineto stroke - - x w 4 div add w 8 div add y h 4 div add M - x w 4 div add y lineto - w 4 div h 8 div rlineto stroke - grestore - } { - % do nothing - } ifelse - } ifelse -} def - -% EPSF import. - -/BeginEPSF { - /b4_Inc_state save def % Save state for cleanup - /dict_count countdictstack def % Count objects on dict stack - /op_count count 1 sub def % Count objects on operand stack - userdict begin - /showpage { } def - 0 setgray 0 setlinecap - 1 setlinewidth 0 setlinejoin - 10 setmiterlimit [ ] 0 setdash newpath - /languagelevel where { - pop languagelevel - 1 ne { - false setstrokeadjust false setoverprint - } if - } if -} bind def - -/EndEPSF { - count op_count sub { pos } repeat % Clean up stacks - countdictstack dict_count sub { end } repeat - b4_Inc_state restore -} bind def - -% Check PostScript language level. -/languagelevel where { - pop /gs_languagelevel languagelevel def -} { - /gs_languagelevel 1 def -} ifelse -%%EndResource -%%BeginResource: procset Enscript-Encoding-88591 1.6 1 -/encoding_vector [ -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/space /exclam /quotedbl /numbersign -/dollar /percent /ampersand /quoteright -/parenleft /parenright /asterisk /plus -/comma /hyphen /period /slash -/zero /one /two /three -/four /five /six /seven -/eight /nine /colon /semicolon -/less /equal /greater /question -/at /A /B /C -/D /E /F /G -/H /I /J /K -/L /M /N /O -/P /Q /R /S -/T /U /V /W -/X /Y /Z /bracketleft -/backslash /bracketright /asciicircum /underscore -/quoteleft /a /b /c -/d /e /f /g -/h /i /j /k -/l /m /n /o -/p /q /r /s -/t /u /v /w -/x /y /z /braceleft -/bar /braceright /tilde /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/space /exclamdown /cent /sterling -/currency /yen /brokenbar /section -/dieresis /copyright /ordfeminine /guillemotleft -/logicalnot /hyphen /registered /macron -/degree /plusminus /twosuperior /threesuperior -/acute /mu /paragraph /bullet -/cedilla /onesuperior /ordmasculine /guillemotright -/onequarter /onehalf /threequarters /questiondown -/Agrave /Aacute /Acircumflex /Atilde -/Adieresis /Aring /AE /Ccedilla -/Egrave /Eacute /Ecircumflex /Edieresis -/Igrave /Iacute /Icircumflex /Idieresis -/Eth /Ntilde /Ograve /Oacute -/Ocircumflex /Otilde /Odieresis /multiply -/Oslash /Ugrave /Uacute /Ucircumflex -/Udieresis /Yacute /Thorn /germandbls -/agrave /aacute /acircumflex /atilde -/adieresis /aring /ae /ccedilla -/egrave /eacute /ecircumflex /edieresis -/igrave /iacute /icircumflex /idieresis -/eth /ntilde /ograve /oacute -/ocircumflex /otilde /odieresis /divide -/oslash /ugrave /uacute /ucircumflex -/udieresis /yacute /thorn /ydieresis -] def -%%EndResource -%%EndProlog -%%BeginSetup -%%IncludeResource: font Courier-Bold -%%IncludeResource: font Courier -/HFpt_w 10 def -/HFpt_h 10 def -/Courier-Bold /HF-gs-font MF -/HF /HF-gs-font findfont [HFpt_w 0 0 HFpt_h 0 0] makefont def -/Courier /F-gs-font MF -/F-gs-font 10 10 SF -/#copies 1 def -/d_page_w 520 def -/d_page_h 747 def -/d_header_x 0 def -/d_header_y 747 def -/d_header_w 520 def -/d_header_h 0 def -/d_footer_x 0 def -/d_footer_y 0 def -/d_footer_w 520 def -/d_footer_h 0 def -/d_output_w 520 def -/d_output_h 747 def -/cols 1 def -userdict/PStoPSxform PStoPSmatrix matrix currentmatrix - matrix invertmatrix matrix concatmatrix - matrix invertmatrix put -%%EndSetup -%%Page: (0,1) 1 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 1 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 701 M -(Network Working Group T. Ylonen) s -5 690 M -(Internet-Draft SSH Communications Security Corp) s -5 679 M -(Expires: March 31, 2004 D. Moffat, Ed.) s -5 668 M -( Sun Microsystems, Inc) s -5 657 M -( Oct 2003) s -5 624 M -( SSH Protocol Architecture) s -5 613 M -( draft-ietf-secsh-architecture-15.txt) s -5 591 M -(Status of this Memo) s -5 569 M -( This document is an Internet-Draft and is in full conformance with) s -5 558 M -( all provisions of Section 10 of RFC2026.) s -5 536 M -( Internet-Drafts are working documents of the Internet Engineering) s -5 525 M -( Task Force \(IETF\), its areas, and its working groups. Note that other) s -5 514 M -( groups may also distribute working documents as Internet-Drafts.) s -5 492 M -( Internet-Drafts are draft documents valid for a maximum of six months) s -5 481 M -( and may be updated, replaced, or obsoleted by other documents at any) s -5 470 M -( time. It is inappropriate to use Internet-Drafts as reference) s -5 459 M -( material or to cite them other than as "work in progress.") s -5 437 M -( The list of current Internet-Drafts can be accessed at http://) s -5 426 M -( www.ietf.org/ietf/1id-abstracts.txt.) s -5 404 M -( The list of Internet-Draft Shadow Directories can be accessed at) s -5 393 M -( http://www.ietf.org/shadow.html.) s -5 371 M -( This Internet-Draft will expire on March 31, 2004.) s -5 349 M -(Copyright Notice) s -5 327 M -( Copyright \(C\) The Internet Society \(2003\). All Rights Reserved.) s -5 305 M -(Abstract) s -5 283 M -( SSH is a protocol for secure remote login and other secure network) s -5 272 M -( services over an insecure network. This document describes the) s -5 261 M -( architecture of the SSH protocol, as well as the notation and) s -5 250 M -( terminology used in SSH protocol documents. It also discusses the SSH) s -5 239 M -( algorithm naming system that allows local extensions. The SSH) s -5 228 M -( protocol consists of three major components: The Transport Layer) s -5 217 M -( Protocol provides server authentication, confidentiality, and) s -5 206 M -( integrity with perfect forward secrecy. The User Authentication) s -5 195 M -( Protocol authenticates the client to the server. The Connection) s -5 184 M -( Protocol multiplexes the encrypted tunnel into several logical) s -5 173 M -( channels. Details of these protocols are described in separate) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 1]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 2 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -( documents.) s -5 668 M -(Table of Contents) s -5 646 M -( 1. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 3) s -5 635 M -( 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3) s -5 624 M -( 3. Specification of Requirements . . . . . . . . . . . . . . . 3) s -5 613 M -( 4. Architecture . . . . . . . . . . . . . . . . . . . . . . . . 3) s -5 602 M -( 4.1 Host Keys . . . . . . . . . . . . . . . . . . . . . . . . . 4) s -5 591 M -( 4.2 Extensibility . . . . . . . . . . . . . . . . . . . . . . . 5) s -5 580 M -( 4.3 Policy Issues . . . . . . . . . . . . . . . . . . . . . . . 5) s -5 569 M -( 4.4 Security Properties . . . . . . . . . . . . . . . . . . . . 6) s -5 558 M -( 4.5 Packet Size and Overhead . . . . . . . . . . . . . . . . . . 6) s -5 547 M -( 4.6 Localization and Character Set Support . . . . . . . . . . . 7) s -5 536 M -( 5. Data Type Representations Used in the SSH Protocols . . . . 8) s -5 525 M -( 6. Algorithm Naming . . . . . . . . . . . . . . . . . . . . . . 10) s -5 514 M -( 7. Message Numbers . . . . . . . . . . . . . . . . . . . . . . 11) s -5 503 M -( 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . 11) s -5 492 M -( 9. Security Considerations . . . . . . . . . . . . . . . . . . 12) s -5 481 M -( 9.1 Pseudo-Random Number Generation . . . . . . . . . . . . . . 12) s -5 470 M -( 9.2 Transport . . . . . . . . . . . . . . . . . . . . . . . . . 13) s -5 459 M -( 9.2.1 Confidentiality . . . . . . . . . . . . . . . . . . . . . . 13) s -5 448 M -( 9.2.2 Data Integrity . . . . . . . . . . . . . . . . . . . . . . . 16) s -5 437 M -( 9.2.3 Replay . . . . . . . . . . . . . . . . . . . . . . . . . . . 16) s -5 426 M -( 9.2.4 Man-in-the-middle . . . . . . . . . . . . . . . . . . . . . 17) s -5 415 M -( 9.2.5 Denial-of-service . . . . . . . . . . . . . . . . . . . . . 19) s -5 404 M -( 9.2.6 Covert Channels . . . . . . . . . . . . . . . . . . . . . . 19) s -5 393 M -( 9.2.7 Forward Secrecy . . . . . . . . . . . . . . . . . . . . . . 20) s -5 382 M -( 9.3 Authentication Protocol . . . . . . . . . . . . . . . . . . 20) s -5 371 M -( 9.3.1 Weak Transport . . . . . . . . . . . . . . . . . . . . . . . 21) s -5 360 M -( 9.3.2 Debug messages . . . . . . . . . . . . . . . . . . . . . . . 21) s -5 349 M -( 9.3.3 Local security policy . . . . . . . . . . . . . . . . . . . 21) s -5 338 M -( 9.3.4 Public key authentication . . . . . . . . . . . . . . . . . 22) s -5 327 M -( 9.3.5 Password authentication . . . . . . . . . . . . . . . . . . 22) s -5 316 M -( 9.3.6 Host based authentication . . . . . . . . . . . . . . . . . 23) s -5 305 M -( 9.4 Connection protocol . . . . . . . . . . . . . . . . . . . . 23) s -5 294 M -( 9.4.1 End point security . . . . . . . . . . . . . . . . . . . . . 23) s -5 283 M -( 9.4.2 Proxy forwarding . . . . . . . . . . . . . . . . . . . . . . 23) s -5 272 M -( 9.4.3 X11 forwarding . . . . . . . . . . . . . . . . . . . . . . . 24) s -5 261 M -( Normative References . . . . . . . . . . . . . . . . . . . . 24) s -5 250 M -( Informative References . . . . . . . . . . . . . . . . . . . 25) s -5 239 M -( Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 27) s -5 228 M -( Intellectual Property and Copyright Statements . . . . . . . 28) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 2]) s -_R -S -PStoPSsaved restore -%%Page: (2,3) 2 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 3 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -(1. Contributors) s -5 668 M -( The major original contributors of this document were: Tatu Ylonen,) s -5 657 M -( Tero Kivinen, Timo J. Rinne, Sami Lehtinen \(all of SSH Communications) s -5 646 M -( Security Corp\), and Markku-Juhani O. Saarinen \(University of) s -5 635 M -( Jyvaskyla\)) s -5 613 M -( The document editor is: [email protected]. Comments on this) s -5 602 M -( internet draft should be sent to the IETF SECSH working group,) s -5 591 M -( details at: http://ietf.org/html.charters/secsh-charter.html) s -5 569 M -(2. Introduction) s -5 547 M -( SSH is a protocol for secure remote login and other secure network) s -5 536 M -( services over an insecure network. It consists of three major) s -5 525 M -( components:) s -5 514 M -( o The Transport Layer Protocol [SSH-TRANS] provides server) s -5 503 M -( authentication, confidentiality, and integrity. It may optionally) s -5 492 M -( also provide compression. The transport layer will typically be) s -5 481 M -( run over a TCP/IP connection, but might also be used on top of any) s -5 470 M -( other reliable data stream.) s -5 459 M -( o The User Authentication Protocol [SSH-USERAUTH] authenticates the) s -5 448 M -( client-side user to the server. It runs over the transport layer) s -5 437 M -( protocol.) s -5 426 M -( o The Connection Protocol [SSH-CONNECT] multiplexes the encrypted) s -5 415 M -( tunnel into several logical channels. It runs over the user) s -5 404 M -( authentication protocol.) s -5 382 M -( The client sends a service request once a secure transport layer) s -5 371 M -( connection has been established. A second service request is sent) s -5 360 M -( after user authentication is complete. This allows new protocols to) s -5 349 M -( be defined and coexist with the protocols listed above.) s -5 327 M -( The connection protocol provides channels that can be used for a wide) s -5 316 M -( range of purposes. Standard methods are provided for setting up) s -5 305 M -( secure interactive shell sessions and for forwarding \("tunneling"\)) s -5 294 M -( arbitrary TCP/IP ports and X11 connections.) s -5 272 M -(3. Specification of Requirements) s -5 250 M -( All documents related to the SSH protocols shall use the keywords) s -5 239 M -( "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",) s -5 228 M -( "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" to describe) s -5 217 M -( requirements. They are to be interpreted as described in [RFC2119].) s -5 195 M -(4. Architecture) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 3]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 4 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -(4.1 Host Keys) s -5 668 M -( Each server host SHOULD have a host key. Hosts MAY have multiple) s -5 657 M -( host keys using multiple different algorithms. Multiple hosts MAY) s -5 646 M -( share the same host key. If a host has keys at all, it MUST have at) s -5 635 M -( least one key using each REQUIRED public key algorithm \(DSS) s -5 624 M -( [FIPS-186]\).) s -5 602 M -( The server host key is used during key exchange to verify that the) s -5 591 M -( client is really talking to the correct server. For this to be) s -5 580 M -( possible, the client must have a priori knowledge of the server's) s -5 569 M -( public host key.) s -5 547 M -( Two different trust models can be used:) s -5 536 M -( o The client has a local database that associates each host name \(as) s -5 525 M -( typed by the user\) with the corresponding public host key. This) s -5 514 M -( method requires no centrally administered infrastructure, and no) s -5 503 M -( third-party coordination. The downside is that the database of) s -5 492 M -( name-to-key associations may become burdensome to maintain.) s -5 481 M -( o The host name-to-key association is certified by some trusted) s -5 470 M -( certification authority. The client only knows the CA root key,) s -5 459 M -( and can verify the validity of all host keys certified by accepted) s -5 448 M -( CAs.) s -5 426 M -( The second alternative eases the maintenance problem, since) s -5 415 M -( ideally only a single CA key needs to be securely stored on the) s -5 404 M -( client. On the other hand, each host key must be appropriately) s -5 393 M -( certified by a central authority before authorization is possible.) s -5 382 M -( Also, a lot of trust is placed on the central infrastructure.) s -5 360 M -( The protocol provides the option that the server name - host key) s -5 349 M -( association is not checked when connecting to the host for the first) s -5 338 M -( time. This allows communication without prior communication of host) s -5 327 M -( keys or certification. The connection still provides protection) s -5 316 M -( against passive listening; however, it becomes vulnerable to active) s -5 305 M -( man-in-the-middle attacks. Implementations SHOULD NOT normally allow) s -5 294 M -( such connections by default, as they pose a potential security) s -5 283 M -( problem. However, as there is no widely deployed key infrastructure) s -5 272 M -( available on the Internet yet, this option makes the protocol much) s -5 261 M -( more usable during the transition time until such an infrastructure) s -5 250 M -( emerges, while still providing a much higher level of security than) s -5 239 M -( that offered by older solutions \(e.g. telnet [RFC-854] and rlogin) s -5 228 M -( [RFC-1282]\).) s -5 206 M -( Implementations SHOULD try to make the best effort to check host) s -5 195 M -( keys. An example of a possible strategy is to only accept a host key) s -5 184 M -( without checking the first time a host is connected, save the key in) s -5 173 M -( a local database, and compare against that key on all future) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 4]) s -_R -S -PStoPSsaved restore -%%Page: (4,5) 3 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 5 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -( connections to that host.) s -5 668 M -( Implementations MAY provide additional methods for verifying the) s -5 657 M -( correctness of host keys, e.g. a hexadecimal fingerprint derived from) s -5 646 M -( the SHA-1 hash of the public key. Such fingerprints can easily be) s -5 635 M -( verified by using telephone or other external communication channels.) s -5 613 M -( All implementations SHOULD provide an option to not accept host keys) s -5 602 M -( that cannot be verified.) s -5 580 M -( We believe that ease of use is critical to end-user acceptance of) s -5 569 M -( security solutions, and no improvement in security is gained if the) s -5 558 M -( new solutions are not used. Thus, providing the option not to check) s -5 547 M -( the server host key is believed to improve the overall security of) s -5 536 M -( the Internet, even though it reduces the security of the protocol in) s -5 525 M -( configurations where it is allowed.) s -5 503 M -(4.2 Extensibility) s -5 481 M -( We believe that the protocol will evolve over time, and some) s -5 470 M -( organizations will want to use their own encryption, authentication) s -5 459 M -( and/or key exchange methods. Central registration of all extensions) s -5 448 M -( is cumbersome, especially for experimental or classified features.) s -5 437 M -( On the other hand, having no central registration leads to conflicts) s -5 426 M -( in method identifiers, making interoperability difficult.) s -5 404 M -( We have chosen to identify algorithms, methods, formats, and) s -5 393 M -( extension protocols with textual names that are of a specific format.) s -5 382 M -( DNS names are used to create local namespaces where experimental or) s -5 371 M -( classified extensions can be defined without fear of conflicts with) s -5 360 M -( other implementations.) s -5 338 M -( One design goal has been to keep the base protocol as simple as) s -5 327 M -( possible, and to require as few algorithms as possible. However, all) s -5 316 M -( implementations MUST support a minimal set of algorithms to ensure) s -5 305 M -( interoperability \(this does not imply that the local policy on all) s -5 294 M -( hosts would necessary allow these algorithms\). The mandatory) s -5 283 M -( algorithms are specified in the relevant protocol documents.) s -5 261 M -( Additional algorithms, methods, formats, and extension protocols can) s -5 250 M -( be defined in separate drafts. See Section Algorithm Naming \(Section) s -5 239 M -( 6\) for more information.) s -5 217 M -(4.3 Policy Issues) s -5 195 M -( The protocol allows full negotiation of encryption, integrity, key) s -5 184 M -( exchange, compression, and public key algorithms and formats.) s -5 173 M -( Encryption, integrity, public key, and compression algorithms can be) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 5]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 6 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -( different for each direction.) s -5 668 M -( The following policy issues SHOULD be addressed in the configuration) s -5 657 M -( mechanisms of each implementation:) s -5 646 M -( o Encryption, integrity, and compression algorithms, separately for) s -5 635 M -( each direction. The policy MUST specify which is the preferred) s -5 624 M -( algorithm \(e.g. the first algorithm listed in each category\).) s -5 613 M -( o Public key algorithms and key exchange method to be used for host) s -5 602 M -( authentication. The existence of trusted host keys for different) s -5 591 M -( public key algorithms also affects this choice.) s -5 580 M -( o The authentication methods that are to be required by the server) s -5 569 M -( for each user. The server's policy MAY require multiple) s -5 558 M -( authentication for some or all users. The required algorithms MAY) s -5 547 M -( depend on the location where the user is trying to log in from.) s -5 536 M -( o The operations that the user is allowed to perform using the) s -5 525 M -( connection protocol. Some issues are related to security; for) s -5 514 M -( example, the policy SHOULD NOT allow the server to start sessions) s -5 503 M -( or run commands on the client machine, and MUST NOT allow) s -5 492 M -( connections to the authentication agent unless forwarding such) s -5 481 M -( connections has been requested. Other issues, such as which TCP/) s -5 470 M -( IP ports can be forwarded and by whom, are clearly issues of local) s -5 459 M -( policy. Many of these issues may involve traversing or bypassing) s -5 448 M -( firewalls, and are interrelated with the local security policy.) s -5 426 M -(4.4 Security Properties) s -5 404 M -( The primary goal of the SSH protocol is improved security on the) s -5 393 M -( Internet. It attempts to do this in a way that is easy to deploy,) s -5 382 M -( even at the cost of absolute security.) s -5 371 M -( o All encryption, integrity, and public key algorithms used are) s -5 360 M -( well-known, well-established algorithms.) s -5 349 M -( o All algorithms are used with cryptographically sound key sizes) s -5 338 M -( that are believed to provide protection against even the strongest) s -5 327 M -( cryptanalytic attacks for decades.) s -5 316 M -( o All algorithms are negotiated, and in case some algorithm is) s -5 305 M -( broken, it is easy to switch to some other algorithm without) s -5 294 M -( modifying the base protocol.) s -5 272 M -( Specific concessions were made to make wide-spread fast deployment) s -5 261 M -( easier. The particular case where this comes up is verifying that) s -5 250 M -( the server host key really belongs to the desired host; the protocol) s -5 239 M -( allows the verification to be left out \(but this is NOT RECOMMENDED\).) s -5 228 M -( This is believed to significantly improve usability in the short) s -5 217 M -( term, until widespread Internet public key infrastructures emerge.) s -5 195 M -(4.5 Packet Size and Overhead) s -5 173 M -( Some readers will worry about the increase in packet size due to new) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 6]) s -_R -S -PStoPSsaved restore -%%Page: (6,7) 4 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 7 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -( headers, padding, and MAC. The minimum packet size is in the order) s -5 679 M -( of 28 bytes \(depending on negotiated algorithms\). The increase is) s -5 668 M -( negligible for large packets, but very significant for one-byte) s -5 657 M -( packets \(telnet-type sessions\). There are, however, several factors) s -5 646 M -( that make this a non-issue in almost all cases:) s -5 635 M -( o The minimum size of a TCP/IP header is 32 bytes. Thus, the) s -5 624 M -( increase is actually from 33 to 51 bytes \(roughly\).) s -5 613 M -( o The minimum size of the data field of an Ethernet packet is 46) s -5 602 M -( bytes [RFC-894]. Thus, the increase is no more than 5 bytes. When) s -5 591 M -( Ethernet headers are considered, the increase is less than 10) s -5 580 M -( percent.) s -5 569 M -( o The total fraction of telnet-type data in the Internet is) s -5 558 M -( negligible, even with increased packet sizes.) s -5 536 M -( The only environment where the packet size increase is likely to have) s -5 525 M -( a significant effect is PPP [RFC-1134] over slow modem lines \(PPP) s -5 514 M -( compresses the TCP/IP headers, emphasizing the increase in packet) s -5 503 M -( size\). However, with modern modems, the time needed to transfer is in) s -5 492 M -( the order of 2 milliseconds, which is a lot faster than people can) s -5 481 M -( type.) s -5 459 M -( There are also issues related to the maximum packet size. To) s -5 448 M -( minimize delays in screen updates, one does not want excessively) s -5 437 M -( large packets for interactive sessions. The maximum packet size is) s -5 426 M -( negotiated separately for each channel.) s -5 404 M -(4.6 Localization and Character Set Support) s -5 382 M -( For the most part, the SSH protocols do not directly pass text that) s -5 371 M -( would be displayed to the user. However, there are some places where) s -5 360 M -( such data might be passed. When applicable, the character set for the) s -5 349 M -( data MUST be explicitly specified. In most places, ISO 10646 with) s -5 338 M -( UTF-8 encoding is used [RFC-2279]. When applicable, a field is also) s -5 327 M -( provided for a language tag [RFC-3066].) s -5 305 M -( One big issue is the character set of the interactive session. There) s -5 294 M -( is no clear solution, as different applications may display data in) s -5 283 M -( different formats. Different types of terminal emulation may also be) s -5 272 M -( employed in the client, and the character set to be used is) s -5 261 M -( effectively determined by the terminal emulation. Thus, no place is) s -5 250 M -( provided for directly specifying the character set or encoding for) s -5 239 M -( terminal session data. However, the terminal emulation type \(e.g.) s -5 228 M -( "vt100"\) is transmitted to the remote site, and it implicitly) s -5 217 M -( specifies the character set and encoding. Applications typically use) s -5 206 M -( the terminal type to determine what character set they use, or the) s -5 195 M -( character set is determined using some external means. The terminal) s -5 184 M -( emulation may also allow configuring the default character set. In) s -5 173 M -( any case, the character set for the terminal session is considered) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 7]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 8 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -( primarily a client local issue.) s -5 668 M -( Internal names used to identify algorithms or protocols are normally) s -5 657 M -( never displayed to users, and must be in US-ASCII.) s -5 635 M -( The client and server user names are inherently constrained by what) s -5 624 M -( the server is prepared to accept. They might, however, occasionally) s -5 613 M -( be displayed in logs, reports, etc. They MUST be encoded using ISO) s -5 602 M -( 10646 UTF-8, but other encodings may be required in some cases. It) s -5 591 M -( is up to the server to decide how to map user names to accepted user) s -5 580 M -( names. Straight bit-wise binary comparison is RECOMMENDED.) s -5 558 M -( For localization purposes, the protocol attempts to minimize the) s -5 547 M -( number of textual messages transmitted. When present, such messages) s -5 536 M -( typically relate to errors, debugging information, or some externally) s -5 525 M -( configured data. For data that is normally displayed, it SHOULD be) s -5 514 M -( possible to fetch a localized message instead of the transmitted) s -5 503 M -( message by using a numerical code. The remaining messages SHOULD be) s -5 492 M -( configurable.) s -5 470 M -(5. Data Type Representations Used in the SSH Protocols) s -5 459 M -( byte) s -5 437 M -( A byte represents an arbitrary 8-bit value \(octet\) [RFC-1700].) s -5 426 M -( Fixed length data is sometimes represented as an array of bytes,) s -5 415 M -( written byte[n], where n is the number of bytes in the array.) s -5 393 M -( boolean) s -5 371 M -( A boolean value is stored as a single byte. The value 0) s -5 360 M -( represents FALSE, and the value 1 represents TRUE. All non-zero) s -5 349 M -( values MUST be interpreted as TRUE; however, applications MUST NOT) s -5 338 M -( store values other than 0 and 1.) s -5 316 M -( uint32) s -5 294 M -( Represents a 32-bit unsigned integer. Stored as four bytes in the) s -5 283 M -( order of decreasing significance \(network byte order\). For) s -5 272 M -( example, the value 699921578 \(0x29b7f4aa\) is stored as 29 b7 f4) s -5 261 M -( aa.) s -5 239 M -( uint64) s -5 217 M -( Represents a 64-bit unsigned integer. Stored as eight bytes in) s -5 206 M -( the order of decreasing significance \(network byte order\).) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 8]) s -_R -S -PStoPSsaved restore -%%Page: (8,9) 5 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 9 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -( string) s -5 668 M -( Arbitrary length binary string. Strings are allowed to contain) s -5 657 M -( arbitrary binary data, including null characters and 8-bit) s -5 646 M -( characters. They are stored as a uint32 containing its length) s -5 635 M -( \(number of bytes that follow\) and zero \(= empty string\) or more) s -5 624 M -( bytes that are the value of the string. Terminating null) s -5 613 M -( characters are not used.) s -5 591 M -( Strings are also used to store text. In that case, US-ASCII is) s -5 580 M -( used for internal names, and ISO-10646 UTF-8 for text that might) s -5 569 M -( be displayed to the user. The terminating null character SHOULD) s -5 558 M -( NOT normally be stored in the string.) s -5 536 M -( For example, the US-ASCII string "testing" is represented as 00 00) s -5 525 M -( 00 07 t e s t i n g. The UTF8 mapping does not alter the encoding) s -5 514 M -( of US-ASCII characters.) s -5 492 M -( mpint) s -5 470 M -( Represents multiple precision integers in two's complement format,) s -5 459 M -( stored as a string, 8 bits per byte, MSB first. Negative numbers) s -5 448 M -( have the value 1 as the most significant bit of the first byte of) s -5 437 M -( the data partition. If the most significant bit would be set for a) s -5 426 M -( positive number, the number MUST be preceded by a zero byte.) s -5 415 M -( Unnecessary leading bytes with the value 0 or 255 MUST NOT be) s -5 404 M -( included. The value zero MUST be stored as a string with zero) s -5 393 M -( bytes of data.) s -5 371 M -( By convention, a number that is used in modular computations in) s -5 360 M -( Z_n SHOULD be represented in the range 0 <= x < n.) s -5 338 M -( Examples:) s -5 327 M -( value \(hex\) representation \(hex\)) s -5 316 M -( ---------------------------------------------------------------) s -5 305 M -( 0 00 00 00 00) s -5 294 M -( 9a378f9b2e332a7 00 00 00 08 09 a3 78 f9 b2 e3 32 a7) s -5 283 M -( 80 00 00 00 02 00 80) s -5 272 M -( -1234 00 00 00 02 ed cc) s -5 261 M -( -deadbeef 00 00 00 05 ff 21 52 41 11) s -5 217 M -( name-list) s -5 195 M -( A string containing a comma separated list of names. A name list) s -5 184 M -( is represented as a uint32 containing its length \(number of bytes) s -5 173 M -( that follow\) followed by a comma-separated list of zero or more) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 9]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 10 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -( names. A name MUST be non-zero length, and it MUST NOT contain a) s -5 679 M -( comma \(','\). Context may impose additional restrictions on the) s -5 668 M -( names; for example, the names in a list may have to be valid) s -5 657 M -( algorithm identifier \(see Algorithm Naming below\), or [RFC-3066]) s -5 646 M -( language tags. The order of the names in a list may or may not be) s -5 635 M -( significant, also depending on the context where the list is is) s -5 624 M -( used. Terminating NUL characters are not used, neither for the) s -5 613 M -( individual names, nor for the list as a whole.) s -5 591 M -( Examples:) s -5 580 M -( value representation \(hex\)) s -5 569 M -( ---------------------------------------) s -5 558 M -( \(\), the empty list 00 00 00 00) s -5 547 M -( \("zlib"\) 00 00 00 04 7a 6c 69 62) s -5 536 M -( \("zlib", "none"\) 00 00 00 09 7a 6c 69 62 2c 6e 6f 6e 65) s -5 481 M -(6. Algorithm Naming) s -5 459 M -( The SSH protocols refer to particular hash, encryption, integrity,) s -5 448 M -( compression, and key exchange algorithms or protocols by names.) s -5 437 M -( There are some standard algorithms that all implementations MUST) s -5 426 M -( support. There are also algorithms that are defined in the protocol) s -5 415 M -( specification but are OPTIONAL. Furthermore, it is expected that) s -5 404 M -( some organizations will want to use their own algorithms.) s -5 382 M -( In this protocol, all algorithm identifiers MUST be printable) s -5 371 M -( US-ASCII non-empty strings no longer than 64 characters. Names MUST) s -5 360 M -( be case-sensitive.) s -5 338 M -( There are two formats for algorithm names:) s -5 327 M -( o Names that do not contain an at-sign \(@\) are reserved to be) s -5 316 M -( assigned by IETF consensus \(RFCs\). Examples include `3des-cbc',) s -5 305 M -( `sha-1', `hmac-sha1', and `zlib' \(the quotes are not part of the) s -5 294 M -( name\). Names of this format MUST NOT be used without first) s -5 283 M -( registering them. Registered names MUST NOT contain an at-sign) s -5 272 M -( \(@\) or a comma \(,\).) s -5 261 M -( o Anyone can define additional algorithms by using names in the) s -5 250 M -( format name@domainname, e.g. "[email protected]". The) s -5 239 M -( format of the part preceding the at sign is not specified; it MUST) s -5 228 M -( consist of US-ASCII characters except at-sign and comma. The part) s -5 217 M -( following the at-sign MUST be a valid fully qualified internet) s -5 206 M -( domain name [RFC-1034] controlled by the person or organization) s -5 195 M -( defining the name. It is up to each domain how it manages its) s -5 184 M -( local namespace.) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 10]) s -_R -S -PStoPSsaved restore -%%Page: (10,11) 6 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 11 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -(7. Message Numbers) s -5 668 M -( SSH packets have message numbers in the range 1 to 255. These numbers) s -5 657 M -( have been allocated as follows:) s -5 624 M -( Transport layer protocol:) s -5 602 M -( 1 to 19 Transport layer generic \(e.g. disconnect, ignore, debug,) s -5 591 M -( etc.\)) s -5 580 M -( 20 to 29 Algorithm negotiation) s -5 569 M -( 30 to 49 Key exchange method specific \(numbers can be reused for) s -5 558 M -( different authentication methods\)) s -5 536 M -( User authentication protocol:) s -5 514 M -( 50 to 59 User authentication generic) s -5 503 M -( 60 to 79 User authentication method specific \(numbers can be) s -5 492 M -( reused for different authentication methods\)) s -5 470 M -( Connection protocol:) s -5 448 M -( 80 to 89 Connection protocol generic) s -5 437 M -( 90 to 127 Channel related messages) s -5 415 M -( Reserved for client protocols:) s -5 393 M -( 128 to 191 Reserved) s -5 371 M -( Local extensions:) s -5 349 M -( 192 to 255 Local extensions) s -5 305 M -(8. IANA Considerations) s -5 283 M -( The initial state of the IANA registry is detailed in [SSH-NUMBERS].) s -5 261 M -( Allocation of the following types of names in the SSH protocols is) s -5 250 M -( assigned by IETF consensus:) s -5 239 M -( o SSH encryption algorithm names,) s -5 228 M -( o SSH MAC algorithm names,) s -5 217 M -( o SSH public key algorithm names \(public key algorithm also implies) s -5 206 M -( encoding and signature/encryption capability\),) s -5 195 M -( o SSH key exchange method names, and) s -5 184 M -( o SSH protocol \(service\) names.) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 11]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 12 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -( These names MUST be printable US-ASCII strings, and MUST NOT contain) s -5 679 M -( the characters at-sign \('@'\), comma \(','\), or whitespace or control) s -5 668 M -( characters \(ASCII codes 32 or less\). Names are case-sensitive, and) s -5 657 M -( MUST NOT be longer than 64 characters.) s -5 635 M -( Names with the at-sign \('@'\) in them are allocated by the owner of) s -5 624 M -( DNS name after the at-sign \(hierarchical allocation in [RFC-2343]\),) s -5 613 M -( otherwise the same restrictions as above.) s -5 591 M -( Each category of names listed above has a separate namespace.) s -5 580 M -( However, using the same name in multiple categories SHOULD be avoided) s -5 569 M -( to minimize confusion.) s -5 547 M -( Message numbers \(see Section Message Numbers \(Section 7\)\) in the) s -5 536 M -( range of 0..191 are allocated via IETF consensus; message numbers in) s -5 525 M -( the 192..255 range \(the "Local extensions" set\) are reserved for) s -5 514 M -( private use.) s -5 492 M -(9. Security Considerations) s -5 470 M -( In order to make the entire body of Security Considerations more) s -5 459 M -( accessible, Security Considerations for the transport,) s -5 448 M -( authentication, and connection documents have been gathered here.) s -5 426 M -( The transport protocol [1] provides a confidential channel over an) s -5 415 M -( insecure network. It performs server host authentication, key) s -5 404 M -( exchange, encryption, and integrity protection. It also derives a) s -5 393 M -( unique session id that may be used by higher-level protocols.) s -5 371 M -( The authentication protocol [2] provides a suite of mechanisms which) s -5 360 M -( can be used to authenticate the client user to the server.) s -5 349 M -( Individual mechanisms specified in the in authentication protocol use) s -5 338 M -( the session id provided by the transport protocol and/or depend on) s -5 327 M -( the security and integrity guarantees of the transport protocol.) s -5 305 M -( The connection protocol [3] specifies a mechanism to multiplex) s -5 294 M -( multiple streams [channels] of data over the confidential and) s -5 283 M -( authenticated transport. It also specifies channels for accessing an) s -5 272 M -( interactive shell, for 'proxy-forwarding' various external protocols) s -5 261 M -( over the secure transport \(including arbitrary TCP/IP protocols\), and) s -5 250 M -( for accessing secure 'subsystems' on the server host.) s -5 228 M -(9.1 Pseudo-Random Number Generation) s -5 206 M -( This protocol binds each session key to the session by including) s -5 195 M -( random, session specific data in the hash used to produce session) s -5 184 M -( keys. Special care should be taken to ensure that all of the random) s -5 173 M -( numbers are of good quality. If the random data here \(e.g., DH) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 12]) s -_R -S -PStoPSsaved restore -%%Page: (12,13) 7 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 13 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -( parameters\) are pseudo-random then the pseudo-random number generator) s -5 679 M -( should be cryptographically secure \(i.e., its next output not easily) s -5 668 M -( guessed even when knowing all previous outputs\) and, furthermore,) s -5 657 M -( proper entropy needs to be added to the pseudo-random number) s -5 646 M -( generator. RFC 1750 [1750] offers suggestions for sources of random) s -5 635 M -( numbers and entropy. Implementors should note the importance of) s -5 624 M -( entropy and the well-meant, anecdotal warning about the difficulty in) s -5 613 M -( properly implementing pseudo-random number generating functions.) s -5 591 M -( The amount of entropy available to a given client or server may) s -5 580 M -( sometimes be less than what is required. In this case one must) s -5 569 M -( either resort to pseudo-random number generation regardless of) s -5 558 M -( insufficient entropy or refuse to run the protocol. The latter is) s -5 547 M -( preferable.) s -5 525 M -(9.2 Transport) s -5 503 M -(9.2.1 Confidentiality) s -5 481 M -( It is beyond the scope of this document and the Secure Shell Working) s -5 470 M -( Group to analyze or recommend specific ciphers other than the ones) s -5 459 M -( which have been established and accepted within the industry. At the) s -5 448 M -( time of this writing, ciphers commonly in use include 3DES, ARCFOUR,) s -5 437 M -( twofish, serpent and blowfish. AES has been accepted by The) s -5 426 M -( published as a US Federal Information Processing Standards [FIPS-197]) s -5 415 M -( and the cryptographic community as being acceptable for this purpose) s -5 404 M -( as well has accepted AES. As always, implementors and users should) s -5 393 M -( check current literature to ensure that no recent vulnerabilities) s -5 382 M -( have been found in ciphers used within products. Implementors should) s -5 371 M -( also check to see which ciphers are considered to be relatively) s -5 360 M -( stronger than others and should recommend their use to users over) s -5 349 M -( relatively weaker ciphers. It would be considered good form for an) s -5 338 M -( implementation to politely and unobtrusively notify a user that a) s -5 327 M -( stronger cipher is available and should be used when a weaker one is) s -5 316 M -( actively chosen.) s -5 294 M -( The "none" cipher is provided for debugging and SHOULD NOT be used) s -5 283 M -( except for that purpose. It's cryptographic properties are) s -5 272 M -( sufficiently described in RFC 2410, which will show that its use does) s -5 261 M -( not meet the intent of this protocol.) s -5 239 M -( The relative merits of these and other ciphers may also be found in) s -5 228 M -( current literature. Two references that may provide information on) s -5 217 M -( the subject are [SCHNEIER] and [KAUFMAN,PERLMAN,SPECINER]. Both of) s -5 206 M -( these describe the CBC mode of operation of certain ciphers and the) s -5 195 M -( weakness of this scheme. Essentially, this mode is theoretically) s -5 184 M -( vulnerable to chosen cipher-text attacks because of the high) s -5 173 M -( predictability of the start of packet sequence. However, this attack) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 13]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 14 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -( is still deemed difficult and not considered fully practicable) s -5 679 M -( especially if relatively longer block sizes are used.) s -5 657 M -( Additionally, another CBC mode attack may be mitigated through the) s -5 646 M -( insertion of packets containing SSH_MSG_IGNORE. Without this) s -5 635 M -( technique, a specific attack may be successful. For this attack) s -5 624 M -( \(commonly known as the Rogaway attack) s -5 613 M -( [ROGAWAY],[DAI],[BELLARE,KOHNO,NAMPREMPRE]\) to work, the attacker) s -5 602 M -( would need to know the IV of the next block that is going to be) s -5 591 M -( encrypted. In CBC mode that is the output of the encryption of the) s -5 580 M -( previous block. If the attacker does not have any way to see the) s -5 569 M -( packet yet \(i.e it is in the internal buffers of the ssh) s -5 558 M -( implementation or even in the kernel\) then this attack will not work.) s -5 547 M -( If the last packet has been sent out to the network \(i.e the attacker) s -5 536 M -( has access to it\) then he can use the attack.) s -5 514 M -( In the optimal case an implementor would need to add an extra packet) s -5 503 M -( only if the packet has been sent out onto the network and there are) s -5 492 M -( no other packets waiting for transmission. Implementors may wish to) s -5 481 M -( check to see if there are any unsent packets awaiting transmission,) s -5 470 M -( but unfortunately it is not normally easy to obtain this information) s -5 459 M -( from the kernel or buffers. If there are not, then a packet) s -5 448 M -( containing SSH_MSG_IGNORE SHOULD be sent. If a new packet is added) s -5 437 M -( to the stream every time the attacker knows the IV that is supposed) s -5 426 M -( to be used for the next packet, then the attacker will not be able to) s -5 415 M -( guess the correct IV, thus the attack will never be successfull.) s -5 393 M -( As an example, consider the following case:) s -5 360 M -( Client Server) s -5 349 M -( ------ ------) s -5 338 M -( TCP\(seq=x, len=500\) ->) s -5 327 M -( contains Record 1) s -5 305 M -( [500 ms passes, no ACK]) s -5 283 M -( TCP\(seq=x, len=1000\) ->) s -5 272 M -( contains Records 1,2) s -5 250 M -( ACK) s -5 217 M -( 1. The Nagle algorithm + TCP retransmits mean that the two records) s -5 206 M -( get coalesced into a single TCP segment) s -5 195 M -( 2. Record 2 is *not* at the beginning of the TCP segment and never) s -5 184 M -( will be, since it gets ACKed.) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 14]) s -_R -S -PStoPSsaved restore -%%Page: (14,15) 8 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 15 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -( 3. Yet, the attack is possible because Record 1 has already been) s -5 679 M -( seen.) s -5 657 M -( As this example indicates, it's totally unsafe to use the existence) s -5 646 M -( of unflushed data in the TCP buffers proper as a guide to whether you) s -5 635 M -( need an empty packet, since when you do the second write\(\), the) s -5 624 M -( buffers will contain the un-ACKed Record 1.) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 15]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 16 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -( On the other hand, it's perfectly safe to have the following) s -5 679 M -( situation:) s -5 646 M -( Client Server) s -5 635 M -( ------ ------) s -5 624 M -( TCP\(seq=x, len=500\) ->) s -5 613 M -( contains SSH_MSG_IGNORE) s -5 591 M -( TCP\(seq=y, len=500\) ->) s -5 580 M -( contains Data) s -5 558 M -( Provided that the IV for second SSH Record is fixed after the data for) s -5 547 M -( the Data packet is determined -i.e. you do:) s -5 536 M -( read from user) s -5 525 M -( encrypt null packet) s -5 514 M -( encrypt data packet) s -5 481 M -(9.2.2 Data Integrity) s -5 459 M -( This protocol does allow the Data Integrity mechanism to be disabled.) s -5 448 M -( Implementors SHOULD be wary of exposing this feature for any purpose) s -5 437 M -( other than debugging. Users and administrators SHOULD be explicitly) s -5 426 M -( warned anytime the "none" MAC is enabled.) s -5 404 M -( So long as the "none" MAC is not used, this protocol provides data) s -5 393 M -( integrity.) s -5 371 M -( Because MACs use a 32 bit sequence number, they might start to leak) s -5 360 M -( information after 2**32 packets have been sent. However, following) s -5 349 M -( the rekeying recommendations should prevent this attack. The) s -5 338 M -( transport protocol [1] recommends rekeying after one gigabyte of) s -5 327 M -( data, and the smallest possible packet is 16 bytes. Therefore,) s -5 316 M -( rekeying SHOULD happen after 2**28 packets at the very most.) s -5 294 M -(9.2.3 Replay) s -5 272 M -( The use of a MAC other than 'none' provides integrity and) s -5 261 M -( authentication. In addition, the transport protocol provides a) s -5 250 M -( unique session identifier \(bound in part to pseudo-random data that) s -5 239 M -( is part of the algorithm and key exchange process\) that can be used) s -5 228 M -( by higher level protocols to bind data to a given session and prevent) s -5 217 M -( replay of data from prior sessions. For example, the authentication) s -5 206 M -( protocol uses this to prevent replay of signatures from previous) s -5 195 M -( sessions. Because public key authentication exchanges are) s -5 184 M -( cryptographically bound to the session \(i.e., to the initial key) s -5 173 M -( exchange\) they cannot be successfully replayed in other sessions.) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 16]) s -_R -S -PStoPSsaved restore -%%Page: (16,17) 9 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 17 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -( Note that the session ID can be made public without harming the) s -5 679 M -( security of the protocol.) s -5 657 M -( If two session happen to have the same session ID [hash of key) s -5 646 M -( exchanges] then packets from one can be replayed against the other.) s -5 635 M -( It must be stressed that the chances of such an occurrence are,) s -5 624 M -( needless to say, minimal when using modern cryptographic methods.) s -5 613 M -( This is all the more so true when specifying larger hash function) s -5 602 M -( outputs and DH parameters.) s -5 580 M -( Replay detection using monotonically increasing sequence numbers as) s -5 569 M -( input to the MAC, or HMAC in some cases, is described in [RFC2085] />) s -5 558 M -( [RFC2246], [RFC2743], [RFC1964], [RFC2025], and [RFC1510]. The) s -5 547 M -( underlying construct is discussed in [RFC2104]. Essentially a) s -5 536 M -( different sequence number in each packet ensures that at least this) s -5 525 M -( one input to the MAC function will be unique and will provide a) s -5 514 M -( nonrecurring MAC output that is not predictable to an attacker. If) s -5 503 M -( the session stays active long enough, however, this sequence number) s -5 492 M -( will wrap. This event may provide an attacker an opportunity to) s -5 481 M -( replay a previously recorded packet with an identical sequence number) s -5 470 M -( but only if the peers have not rekeyed since the transmission of the) s -5 459 M -( first packet with that sequence number. If the peers have rekeyed,) s -5 448 M -( then the replay will be detected as the MAC check will fail. For) s -5 437 M -( this reason, it must be emphasized that peers MUST rekey before a) s -5 426 M -( wrap of the sequence numbers. Naturally, if an attacker does attempt) s -5 415 M -( to replay a captured packet before the peers have rekeyed, then the) s -5 404 M -( receiver of the duplicate packet will not be able to validate the MAC) s -5 393 M -( and it will be discarded. The reason that the MAC will fail is) s -5 382 M -( because the receiver will formulate a MAC based upon the packet) s -5 371 M -( contents, the shared secret, and the expected sequence number. Since) s -5 360 M -( the replayed packet will not be using that expected sequence number) s -5 349 M -( \(the sequence number of the replayed packet will have already been) s -5 338 M -( passed by the receiver\) then the calculated MAC will not match the) s -5 327 M -( MAC received with the packet.) s -5 305 M -(9.2.4 Man-in-the-middle) s -5 283 M -( This protocol makes no assumptions nor provisions for an) s -5 272 M -( infrastructure or means for distributing the public keys of hosts. It) s -5 261 M -( is expected that this protocol will sometimes be used without first) s -5 250 M -( verifying the association between the server host key and the server) s -5 239 M -( host name. Such usage is vulnerable to man-in-the-middle attacks.) s -5 228 M -( This section describes this and encourages administrators and users) s -5 217 M -( to understand the importance of verifying this association before any) s -5 206 M -( session is initiated.) s -5 184 M -( There are three cases of man-in-the-middle attacks to consider. The) s -5 173 M -( first is where an attacker places a device between the client and the) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 17]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 18 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -( server before the session is initiated. In this case, the attack) s -5 679 M -( device is trying to mimic the legitimate server and will offer its) s -5 668 M -( public key to the client when the client initiates a session. If it) s -5 657 M -( were to offer the public key of the server, then it would not be able) s -5 646 M -( to decrypt or sign the transmissions between the legitimate server) s -5 635 M -( and the client unless it also had access to the private-key of the) s -5 624 M -( host. The attack device will also, simultaneously to this, initiate) s -5 613 M -( a session to the legitimate server masquerading itself as the client.) s -5 602 M -( If the public key of the server had been securely distributed to the) s -5 591 M -( client prior to that session initiation, the key offered to the) s -5 580 M -( client by the attack device will not match the key stored on the) s -5 569 M -( client. In that case, the user SHOULD be given a warning that the) s -5 558 M -( offered host key does not match the host key cached on the client.) s -5 547 M -( As described in Section 3.1 of [ARCH], the user may be free to accept) s -5 536 M -( the new key and continue the session. It is RECOMMENDED that the) s -5 525 M -( warning provide sufficient information to the user of the client) s -5 514 M -( device so they may make an informed decision. If the user chooses to) s -5 503 M -( continue the session with the stored public-key of the server \(not) s -5 492 M -( the public-key offered at the start of the session\), then the session) s -5 481 M -( specific data between the attacker and server will be different) s -5 470 M -( between the client-to-attacker session and the attacker-to-server) s -5 459 M -( sessions due to the randomness discussed above. From this, the) s -5 448 M -( attacker will not be able to make this attack work since the attacker) s -5 437 M -( will not be able to correctly sign packets containing this session) s -5 426 M -( specific data from the server since he does not have the private key) s -5 415 M -( of that server.) s -5 393 M -( The second case that should be considered is similar to the first) s -5 382 M -( case in that it also happens at the time of connection but this case) s -5 371 M -( points out the need for the secure distribution of server public) s -5 360 M -( keys. If the server public keys are not securely distributed then) s -5 349 M -( the client cannot know if it is talking to the intended server. An) s -5 338 M -( attacker may use social engineering techniques to pass off server) s -5 327 M -( keys to unsuspecting users and may then place a man-in-the-middle) s -5 316 M -( attack device between the legitimate server and the clients. If this) s -5 305 M -( is allowed to happen then the clients will form client-to-attacker) s -5 294 M -( sessions and the attacker will form attacker-to-server sessions and) s -5 283 M -( will be able to monitor and manipulate all of the traffic between the) s -5 272 M -( clients and the legitimate servers. Server administrators are) s -5 261 M -( encouraged to make host key fingerprints available for checking by) s -5 250 M -( some means whose security does not rely on the integrity of the) s -5 239 M -( actual host keys. Possible mechanisms are discussed in Section 3.1) s -5 228 M -( of [SSH-ARCH] and may also include secured Web pages, physical pieces) s -5 217 M -( of paper, etc. Implementors SHOULD provide recommendations on how) s -5 206 M -( best to do this with their implementation. Because the protocol is) s -5 195 M -( extensible, future extensions to the protocol may provide better) s -5 184 M -( mechanisms for dealing with the need to know the server's host key) s -5 173 M -( before connecting. For example, making the host key fingerprint) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 18]) s -_R -S -PStoPSsaved restore -%%Page: (18,19) 10 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 19 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -( available through a secure DNS lookup, or using kerberos over gssapi) s -5 679 M -( during key exchange to authenticate the server are possibilities.) s -5 657 M -( In the third man-in-the-middle case, attackers may attempt to) s -5 646 M -( manipulate packets in transit between peers after the session has) s -5 635 M -( been established. As described in the Replay part of this section, a) s -5 624 M -( successful attack of this nature is very improbable. As in the) s -5 613 M -( Replay section, this reasoning does assume that the MAC is secure and) s -5 602 M -( that it is infeasible to construct inputs to a MAC algorithm to give) s -5 591 M -( a known output. This is discussed in much greater detail in Section) s -5 580 M -( 6 of RFC 2104. If the MAC algorithm has a vulnerability or is weak) s -5 569 M -( enough, then the attacker may be able to specify certain inputs to) s -5 558 M -( yield a known MAC. With that they may be able to alter the contents) s -5 547 M -( of a packet in transit. Alternatively the attacker may be able to) s -5 536 M -( exploit the algorithm vulnerability or weakness to find the shared) s -5 525 M -( secret by reviewing the MACs from captured packets. In either of) s -5 514 M -( those cases, an attacker could construct a packet or packets that) s -5 503 M -( could be inserted into an SSH stream. To prevent that, implementors) s -5 492 M -( are encouraged to utilize commonly accepted MAC algorithms and) s -5 481 M -( administrators are encouraged to watch current literature and) s -5 470 M -( discussions of cryptography to ensure that they are not using a MAC) s -5 459 M -( algorithm that has a recently found vulnerability or weakness.) s -5 437 M -( In summary, the use of this protocol without a reliable association) s -5 426 M -( of the binding between a host and its host keys is inherently) s -5 415 M -( insecure and is NOT RECOMMENDED. It may however be necessary in) s -5 404 M -( non-security critical environments, and will still provide protection) s -5 393 M -( against passive attacks. Implementors of protocols and applications) s -5 382 M -( running on top of this protocol should keep this possibility in mind.) s -5 360 M -(9.2.5 Denial-of-service) s -5 338 M -( This protocol is designed to be used over a reliable transport. If) s -5 327 M -( transmission errors or message manipulation occur, the connection is) s -5 316 M -( closed. The connection SHOULD be re-established if this occurs.) s -5 305 M -( Denial of service attacks of this type \("wire cutter"\) are almost) s -5 294 M -( impossible to avoid.) s -5 272 M -( In addition, this protocol is vulnerable to Denial of Service attacks) s -5 261 M -( because an attacker can force the server to go through the CPU and) s -5 250 M -( memory intensive tasks of connection setup and key exchange without) s -5 239 M -( authenticating. Implementors SHOULD provide features that make this) s -5 228 M -( more difficult. For example, only allowing connections from a subset) s -5 217 M -( of IPs known to have valid users.) s -5 195 M -(9.2.6 Covert Channels) s -5 173 M -( The protocol was not designed to eliminate covert channels. For) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 19]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 20 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -( example, the padding, SSH_MSG_IGNORE messages, and several other) s -5 679 M -( places in the protocol can be used to pass covert information, and) s -5 668 M -( the recipient has no reliable way to verify whether such information) s -5 657 M -( is being sent.) s -5 635 M -(9.2.7 Forward Secrecy) s -5 613 M -( It should be noted that the Diffie-Hellman key exchanges may provide) s -5 602 M -( perfect forward secrecy \(PFS\). PFS is essentially defined as the) s -5 591 M -( cryptographic property of a key-establishment protocol in which the) s -5 580 M -( compromise of a session key or long-term private key after a given) s -5 569 M -( session does not cause the compromise of any earlier session. [ANSI) s -5 558 M -( T1.523-2001] SSHv2 sessions resulting from a key exchange using) s -5 547 M -( diffie-hellman-group1-sha1 are secure even if private keying/) s -5 536 M -( authentication material is later revealed, but not if the session) s -5 525 M -( keys are revealed. So, given this definition of PFS, SSHv2 does have) s -5 514 M -( PFS. It is hoped that all other key exchange mechanisms proposed and) s -5 503 M -( used in the future will also provide PFS. This property is not) s -5 492 M -( commuted to any of the applications or protocols using SSH as a) s -5 481 M -( transport however. The transport layer of SSH provides) s -5 470 M -( confidentiality for password authentication and other methods that) s -5 459 M -( rely on secret data.) s -5 437 M -( Of course, if the DH private parameters for the client and server are) s -5 426 M -( revealed then the session key is revealed, but these items can be) s -5 415 M -( thrown away after the key exchange completes. It's worth pointing) s -5 404 M -( out that these items should not be allowed to end up on swap space) s -5 393 M -( and that they should be erased from memory as soon as the key) s -5 382 M -( exchange completes.) s -5 360 M -(9.3 Authentication Protocol) s -5 338 M -( The purpose of this protocol is to perform client user) s -5 327 M -( authentication. It assumes that this run over a secure transport) s -5 316 M -( layer protocol, which has already authenticated the server machine,) s -5 305 M -( established an encrypted communications channel, and computed a) s -5 294 M -( unique session identifier for this session.) s -5 272 M -( Several authentication methods with different security) s -5 261 M -( characteristics are allowed. It is up to the server's local policy) s -5 250 M -( to decide which methods \(or combinations of methods\) it is willing to) s -5 239 M -( accept for each user. Authentication is no stronger than the weakest) s -5 228 M -( combination allowed.) s -5 206 M -( The server may go into a "sleep" period after repeated unsuccessful) s -5 195 M -( authentication attempts to make key search more difficult for) s -5 184 M -( attackers. Care should be taken so that this doesn't become a) s -5 173 M -( self-denial of service vector.) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 20]) s -_R -S -PStoPSsaved restore -%%Page: (20,21) 11 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 21 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -(9.3.1 Weak Transport) s -5 668 M -( If the transport layer does not provide confidentiality,) s -5 657 M -( authentication methods that rely on secret data SHOULD be disabled.) s -5 646 M -( If it does not provide strong integrity protection, requests to) s -5 635 M -( change authentication data \(e.g. a password change\) SHOULD be) s -5 624 M -( disabled to prevent an attacker from modifying the ciphertext) s -5 613 M -( without being noticed, or rendering the new authentication data) s -5 602 M -( unusable \(denial of service\).) s -5 580 M -( The assumption as stated above that the Authentication Protocol only) s -5 569 M -( run over a secure transport that has previously authenticated the) s -5 558 M -( server is very important to note. People deploying SSH are reminded) s -5 547 M -( of the consequences of man-in-the-middle attacks if the client does) s -5 536 M -( not have a very strong a priori association of the server with the) s -5 525 M -( host key of that server. Specifically for the case of the) s -5 514 M -( Authentication Protocol the client may form a session to a) s -5 503 M -( man-in-the-middle attack device and divulge user credentials such as) s -5 492 M -( their username and password. Even in the cases of authentication) s -5 481 M -( where no user credentials are divulged, an attacker may still gain) s -5 470 M -( information they shouldn't have by capturing key-strokes in much the) s -5 459 M -( same way that a honeypot works.) s -5 437 M -(9.3.2 Debug messages) s -5 415 M -( Special care should be taken when designing debug messages. These) s -5 404 M -( messages may reveal surprising amounts of information about the host) s -5 393 M -( if not properly designed. Debug messages can be disabled \(during) s -5 382 M -( user authentication phase\) if high security is required.) s -5 371 M -( Administrators of host machines should make all attempts to) s -5 360 M -( compartmentalize all event notification messages and protect them) s -5 349 M -( from unwarranted observation. Developers should be aware of the) s -5 338 M -( sensitive nature of some of the normal event messages and debug) s -5 327 M -( messages and may want to provide guidance to administrators on ways) s -5 316 M -( to keep this information away from unauthorized people. Developers) s -5 305 M -( should consider minimizing the amount of sensitive information) s -5 294 M -( obtainable by users during the authentication phase in accordance) s -5 283 M -( with the local policies. For this reason, it is RECOMMENDED that) s -5 272 M -( debug messages be initially disabled at the time of deployment and) s -5 261 M -( require an active decision by an administrator to allow them to be) s -5 250 M -( enabled. It is also RECOMMENDED that a message expressing this) s -5 239 M -( concern be presented to the administrator of a system when the action) s -5 228 M -( is taken to enable debugging messages.) s -5 206 M -(9.3.3 Local security policy) s -5 184 M -( Implementer MUST ensure that the credentials provided validate the) s -5 173 M -( professed user and also MUST ensure that the local policy of the) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 21]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 22 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -( server permits the user the access requested. In particular, because) s -5 679 M -( of the flexible nature of the SSH connection protocol, it may not be) s -5 668 M -( possible to determine the local security policy, if any, that should) s -5 657 M -( apply at the time of authentication because the kind of service being) s -5 646 M -( requested is not clear at that instant. For example, local policy) s -5 635 M -( might allow a user to access files on the server, but not start an) s -5 624 M -( interactive shell. However, during the authentication protocol, it is) s -5 613 M -( not known whether the user will be accessing files or attempting to) s -5 602 M -( use an interactive shell, or even both. In any event, where local) s -5 591 M -( security policy for the server host exists, it MUST be applied and) s -5 580 M -( enforced correctly.) s -5 558 M -( Implementors are encouraged to provide a default local policy and) s -5 547 M -( make its parameters known to administrators and users. At the) s -5 536 M -( discretion of the implementors, this default policy may be along the) s -5 525 M -( lines of 'anything goes' where there are no restrictions placed upon) s -5 514 M -( users, or it may be along the lines of 'excessively restrictive' in) s -5 503 M -( which case the administrators will have to actively make changes to) s -5 492 M -( this policy to meet their needs. Alternatively, it may be some) s -5 481 M -( attempt at providing something practical and immediately useful to) s -5 470 M -( the administrators of the system so they don't have to put in much) s -5 459 M -( effort to get SSH working. Whatever choice is made MUST be applied) s -5 448 M -( and enforced as required above.) s -5 426 M -(9.3.4 Public key authentication) s -5 404 M -( The use of public-key authentication assumes that the client host has) s -5 393 M -( not been compromised. It also assumes that the private-key of the) s -5 382 M -( server host has not been compromised.) s -5 360 M -( This risk can be mitigated by the use of passphrases on private keys;) s -5 349 M -( however, this is not an enforceable policy. The use of smartcards,) s -5 338 M -( or other technology to make passphrases an enforceable policy is) s -5 327 M -( suggested.) s -5 305 M -( The server could require both password and public-key authentication,) s -5 294 M -( however, this requires the client to expose its password to the) s -5 283 M -( server \(see section on password authentication below.\)) s -5 261 M -(9.3.5 Password authentication) s -5 239 M -( The password mechanism as specified in the authentication protocol) s -5 228 M -( assumes that the server has not been compromised. If the server has) s -5 217 M -( been compromised, using password authentication will reveal a valid) s -5 206 M -( username / password combination to the attacker, which may lead to) s -5 195 M -( further compromises.) s -5 173 M -( This vulnerability can be mitigated by using an alternative form of) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 22]) s -_R -S -PStoPSsaved restore -%%Page: (22,23) 12 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 23 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -( authentication. For example, public-key authentication makes no) s -5 679 M -( assumptions about security on the server.) s -5 657 M -(9.3.6 Host based authentication) s -5 635 M -( Host based authentication assumes that the client has not been) s -5 624 M -( compromised. There are no mitigating strategies, other than to use) s -5 613 M -( host based authentication in combination with another authentication) s -5 602 M -( method.) s -5 580 M -(9.4 Connection protocol) s -5 558 M -(9.4.1 End point security) s -5 536 M -( End point security is assumed by the connection protocol. If the) s -5 525 M -( server has been compromised, any terminal sessions, port forwarding,) s -5 514 M -( or systems accessed on the host are compromised. There are no) s -5 503 M -( mitigating factors for this.) s -5 481 M -( If the client end point has been compromised, and the server fails to) s -5 470 M -( stop the attacker at the authentication protocol, all services) s -5 459 M -( exposed \(either as subsystems or through forwarding\) will be) s -5 448 M -( vulnerable to attack. Implementors SHOULD provide mechanisms for) s -5 437 M -( administrators to control which services are exposed to limit the) s -5 426 M -( vulnerability of other services.) s -5 404 M -( These controls might include controlling which machines and ports can) s -5 393 M -( be target in 'port-forwarding' operations, which users are allowed to) s -5 382 M -( use interactive shell facilities, or which users are allowed to use) s -5 371 M -( exposed subsystems.) s -5 349 M -(9.4.2 Proxy forwarding) s -5 327 M -( The SSH connection protocol allows for proxy forwarding of other) s -5 316 M -( protocols such as SNMP, POP3, and HTTP. This may be a concern for) s -5 305 M -( network administrators who wish to control the access of certain) s -5 294 M -( applications by users located outside of their physical location.) s -5 283 M -( Essentially, the forwarding of these protocols may violate site) s -5 272 M -( specific security policies as they may be undetectably tunneled) s -5 261 M -( through a firewall. Implementors SHOULD provide an administrative) s -5 250 M -( mechanism to control the proxy forwarding functionality so that site) s -5 239 M -( specific security policies may be upheld.) s -5 217 M -( In addition, a reverse proxy forwarding functionality is available,) s -5 206 M -( which again can be used to bypass firewall controls.) s -5 184 M -( As indicated above, end-point security is assumed during proxy) s -5 173 M -( forwarding operations. Failure of end-point security will compromise) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 23]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 24 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -( all data passed over proxy forwarding.) s -5 668 M -(9.4.3 X11 forwarding) s -5 646 M -( Another form of proxy forwarding provided by the ssh connection) s -5 635 M -( protocol is the forwarding of the X11 protocol. If end-point) s -5 624 M -( security has been compromised, X11 forwarding may allow attacks) s -5 613 M -( against the X11 server. Users and administrators should, as a matter) s -5 602 M -( of course, use appropriate X11 security mechanisms to prevent) s -5 591 M -( unauthorized use of the X11 server. Implementors, administrators and) s -5 580 M -( users who wish to further explore the security mechanisms of X11 are) s -5 569 M -( invited to read [SCHEIFLER] and analyze previously reported problems) s -5 558 M -( with the interactions between SSH forwarding and X11 in CERT) s -5 547 M -( vulnerabilities VU#363181 and VU#118892 [CERT].) s -5 525 M -( X11 display forwarding with SSH, by itself, is not sufficient to) s -5 514 M -( correct well known problems with X11 security [VENEMA]. However, X11) s -5 503 M -( display forwarding in SSHv2 \(or other, secure protocols\), combined) s -5 492 M -( with actual and pseudo-displays which accept connections only over) s -5 481 M -( local IPC mechanisms authorized by permissions or ACLs, does correct) s -5 470 M -( many X11 security problems as long as the "none" MAC is not used. It) s -5 459 M -( is RECOMMENDED that X11 display implementations default to allowing) s -5 448 M -( display opens only over local IPC. It is RECOMMENDED that SSHv2) s -5 437 M -( server implementations that support X11 forwarding default to) s -5 426 M -( allowing display opens only over local IPC. On single-user systems) s -5 415 M -( it might be reasonable to default to allowing local display opens) s -5 404 M -( over TCP/IP.) s -5 382 M -( Implementors of the X11 forwarding protocol SHOULD implement the) s -5 371 M -( magic cookie access checking spoofing mechanism as described in) s -5 360 M -( [ssh-connect] as an additional mechanism to prevent unauthorized use) s -5 349 M -( of the proxy.) s -5 327 M -(Normative References) s -5 305 M -( [SSH-ARCH]) s -5 294 M -( Ylonen, T., "SSH Protocol Architecture", I-D) s -5 283 M -( draft-ietf-architecture-15.txt, Oct 2003.) s -5 261 M -( [SSH-TRANS]) s -5 250 M -( Ylonen, T., "SSH Transport Layer Protocol", I-D) s -5 239 M -( draft-ietf-transport-17.txt, Oct 2003.) s -5 217 M -( [SSH-USERAUTH]) s -5 206 M -( Ylonen, T., "SSH Authentication Protocol", I-D) s -5 195 M -( draft-ietf-userauth-18.txt, Oct 2003.) s -5 173 M -( [SSH-CONNECT]) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 24]) s -_R -S -PStoPSsaved restore -%%Page: (24,25) 13 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 25 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -( Ylonen, T., "SSH Connection Protocol", I-D) s -5 679 M -( draft-ietf-connect-18.txt, Oct 2003.) s -5 657 M -( [SSH-NUMBERS]) s -5 646 M -( Lehtinen, S. and D. Moffat, "SSH Protocol Assigned) s -5 635 M -( Numbers", I-D draft-ietf-secsh-assignednumbers-05.txt, Oct) s -5 624 M -( 2003.) s -5 602 M -( [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate) s -5 591 M -( Requirement Levels", BCP 14, RFC 2119, March 1997.) s -5 569 M -(Informative References) s -5 547 M -( [FIPS-186]) s -5 536 M -( Federal Information Processing Standards Publication,) s -5 525 M -( "FIPS PUB 186, Digital Signature Standard", May 1994.) s -5 503 M -( [FIPS-197]) s -5 492 M -( National Institue of Standards and Technology, "FIPS 197,) s -5 481 M -( Specification for the Advanced Encryption Standard",) s -5 470 M -( November 2001.) s -5 448 M -( [ANSI T1.523-2001]) s -5 437 M -( American National Standards Insitute, Inc., "Telecom) s -5 426 M -( Glossary 2000", February 2001.) s -5 404 M -( [SCHEIFLER]) s -5 393 M -( Scheifler, R., "X Window System : The Complete Reference) s -5 382 M -( to Xlib, X Protocol, Icccm, Xlfd, 3rd edition.", Digital) s -5 371 M -( Press ISBN 1555580882, Feburary 1992.) s -5 349 M -( [RFC0854] Postel, J. and J. Reynolds, "Telnet Protocol) s -5 338 M -( Specification", STD 8, RFC 854, May 1983.) s -5 316 M -( [RFC0894] Hornig, C., "Standard for the transmission of IP datagrams) s -5 305 M -( over Ethernet networks", STD 41, RFC 894, April 1984.) s -5 283 M -( [RFC1034] Mockapetris, P., "Domain names - concepts and facilities",) s -5 272 M -( STD 13, RFC 1034, November 1987.) s -5 250 M -( [RFC1134] Perkins, D., "Point-to-Point Protocol: A proposal for) s -5 239 M -( multi-protocol transmission of datagrams over) s -5 228 M -( Point-to-Point links", RFC 1134, November 1989.) s -5 206 M -( [RFC1282] Kantor, B., "BSD Rlogin", RFC 1282, December 1991.) s -5 184 M -( [RFC1510] Kohl, J. and B. Neuman, "The Kerberos Network) s -5 173 M -( Authentication Service \(V5\)", RFC 1510, September 1993.) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 25]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 26 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -( [RFC1700] Reynolds, J. and J. Postel, "Assigned Numbers", RFC 1700,) s -5 679 M -( October 1994.) s -5 657 M -( [RFC1750] Eastlake, D., Crocker, S. and J. Schiller, "Randomness) s -5 646 M -( Recommendations for Security", RFC 1750, December 1994.) s -5 624 M -( [RFC3066] Alvestrand, H., "Tags for the Identification of) s -5 613 M -( Languages", BCP 47, RFC 3066, January 2001.) s -5 591 M -( [RFC1964] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC) s -5 580 M -( 1964, June 1996.) s -5 558 M -( [RFC2025] Adams, C., "The Simple Public-Key GSS-API Mechanism) s -5 547 M -( \(SPKM\)", RFC 2025, October 1996.) s -5 525 M -( [RFC2085] Oehler, M. and R. Glenn, "HMAC-MD5 IP Authentication with) s -5 514 M -( Replay Prevention", RFC 2085, February 1997.) s -5 492 M -( [RFC2104] Krawczyk, H., Bellare, M. and R. Canetti, "HMAC:) s -5 481 M -( Keyed-Hashing for Message Authentication", RFC 2104,) s -5 470 M -( February 1997.) s -5 448 M -( [RFC2246] Dierks, T., Allen, C., Treese, W., Karlton, P., Freier, A.) s -5 437 M -( and P. Kocher, "The TLS Protocol Version 1.0", RFC 2246,) s -5 426 M -( January 1999.) s -5 404 M -( [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO) s -5 393 M -( 10646", RFC 2279, January 1998.) s -5 371 M -( [RFC2410] Glenn, R. and S. Kent, "The NULL Encryption Algorithm and) s -5 360 M -( Its Use With IPsec", RFC 2410, November 1998.) s -5 338 M -( [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an) s -5 327 M -( IANA Considerations Section in RFCs", BCP 26, RFC 2434,) s -5 316 M -( October 1998.) s -5 294 M -( [RFC2743] Linn, J., "Generic Security Service Application Program) s -5 283 M -( Interface Version 2, Update 1", RFC 2743, January 2000.) s -5 261 M -( [SCHNEIER]) s -5 250 M -( Schneier, B., "Applied Cryptography Second Edition:) s -5 239 M -( protocols algorithms and source in code in C", 1996.) s -5 217 M -( [KAUFMAN,PERLMAN,SPECINER]) s -5 206 M -( Kaufman, C., Perlman, R. and M. Speciner, "Network) s -5 195 M -( Security: PRIVATE Communication in a PUBLIC World", 1995.) s -5 173 M -( [CERT] CERT Coordination Center, The., "http://www.cert.org/nav/) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 26]) s -_R -S -PStoPSsaved restore -%%Page: (26,27) 14 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 27 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -( index_red.html".) s -5 668 M -( [VENEMA] Venema, W., "Murphy's Law and Computer Security",) s -5 657 M -( Proceedings of 6th USENIX Security Symposium, San Jose CA) s -5 646 M -( http://www.usenix.org/publications/library/proceedings/) s -5 635 M -( sec96/venema.html, July 1996.) s -5 613 M -( [ROGAWAY] Rogaway, P., "Problems with Proposed IP Cryptography",) s -5 602 M -( Unpublished paper http://www.cs.ucdavis.edu/~rogaway/) s -5 591 M -( papers/draft-rogaway-ipsec-comments-00.txt, 1996.) s -5 569 M -( [DAI] Dai, W., "An attack against SSH2 protocol", Email to the) s -5 558 M -( SECSH Working Group [email protected] ftp://) s -5 547 M -( ftp.ietf.org/ietf-mail-archive/secsh/2002-02.mail, Feb) s -5 536 M -( 2002.) s -5 514 M -( [BELLARE,KOHNO,NAMPREMPRE]) s -5 503 M -( Bellaire, M., Kohno, T. and C. Namprempre, "Authenticated) s -5 492 M -( Encryption in SSH: Fixing the SSH Binary Packet Protocol",) s -5 481 M -( , Sept 2002.) s -5 448 M -(Authors' Addresses) s -5 426 M -( Tatu Ylonen) s -5 415 M -( SSH Communications Security Corp) s -5 404 M -( Fredrikinkatu 42) s -5 393 M -( HELSINKI FIN-00100) s -5 382 M -( Finland) s -5 360 M -( EMail: [email protected]) s -5 327 M -( Darren J. Moffat \(editor\)) s -5 316 M -( Sun Microsystems, Inc) s -5 305 M -( 17 Network Circle) s -5 294 M -( Menlo Park CA 94025) s -5 283 M -( USA) s -5 261 M -( EMail: [email protected]) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 27]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 28 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -(Intellectual Property Statement) s -5 668 M -( The IETF takes no position regarding the validity or scope of any) s -5 657 M -( intellectual property or other rights that might be claimed to) s -5 646 M -( pertain to the implementation or use of the technology described in) s -5 635 M -( this document or the extent to which any license under such rights) s -5 624 M -( might or might not be available; neither does it represent that it) s -5 613 M -( has made any effort to identify any such rights. Information on the) s -5 602 M -( IETF's procedures with respect to rights in standards-track and) s -5 591 M -( standards-related documentation can be found in BCP-11. Copies of) s -5 580 M -( claims of rights made available for publication and any assurances of) s -5 569 M -( licenses to be made available, or the result of an attempt made to) s -5 558 M -( obtain a general license or permission for the use of such) s -5 547 M -( proprietary rights by implementors or users of this specification can) s -5 536 M -( be obtained from the IETF Secretariat.) s -5 514 M -( The IETF invites any interested party to bring to its attention any) s -5 503 M -( copyrights, patents or patent applications, or other proprietary) s -5 492 M -( rights which may cover technology that may be required to practice) s -5 481 M -( this standard. Please address the information to the IETF Executive) s -5 470 M -( Director.) s -5 448 M -( The IETF has been notified of intellectual property rights claimed in) s -5 437 M -( regard to some or all of the specification contained in this) s -5 426 M -( document. For more information consult the online list of claimed) s -5 415 M -( rights.) s -5 382 M -(Full Copyright Statement) s -5 360 M -( Copyright \(C\) The Internet Society \(2003\). All Rights Reserved.) s -5 338 M -( This document and translations of it may be copied and furnished to) s -5 327 M -( others, and derivative works that comment on or otherwise explain it) s -5 316 M -( or assist in its implementation may be prepared, copied, published) s -5 305 M -( and distributed, in whole or in part, without restriction of any) s -5 294 M -( kind, provided that the above copyright notice and this paragraph are) s -5 283 M -( included on all such copies and derivative works. However, this) s -5 272 M -( document itself may not be modified in any way, such as by removing) s -5 261 M -( the copyright notice or references to the Internet Society or other) s -5 250 M -( Internet organizations, except as needed for the purpose of) s -5 239 M -( developing Internet standards in which case the procedures for) s -5 228 M -( copyrights defined in the Internet Standards process must be) s -5 217 M -( followed, or as required to translate it into languages other than) s -5 206 M -( English.) s -5 184 M -( The limited permissions granted above are perpetual and will not be) s -5 173 M -( revoked by the Internet Society or its successors or assignees.) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 28]) s -_R -S -PStoPSsaved restore -%%Page: (28,29) 15 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 29 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Protocol Architecture Oct 2003) s -5 690 M -( This document and the information contained herein is provided on an) s -5 679 M -( "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING) s -5 668 M -( TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING) s -5 657 M -( BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION) s -5 646 M -( HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF) s -5 635 M -( MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.) s -5 602 M -(Acknowledgment) s -5 580 M -( Funding for the RFC Editor function is currently provided by the) s -5 569 M -( Internet Society.) s -5 129 M -(Ylonen & Moffat Expires March 31, 2004 [Page 29]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -showpage -PStoPSsaved restore -%%Trailer -%%Pages: 29 -%%DocumentNeededResources: font Courier-Bold Courier -%%EOF diff --git a/lib/ssh/doc/standard/draft-ietf-secsh-architecture-15.txt b/lib/ssh/doc/standard/draft-ietf-secsh-architecture-15.txt deleted file mode 100644 index 18070e8485..0000000000 --- a/lib/ssh/doc/standard/draft-ietf-secsh-architecture-15.txt +++ /dev/null @@ -1,1624 +0,0 @@ - - - -Network Working Group T. Ylonen -Internet-Draft SSH Communications Security Corp -Expires: March 31, 2004 D. Moffat, Ed. - Sun Microsystems, Inc - Oct 2003 - - - SSH Protocol Architecture - draft-ietf-secsh-architecture-15.txt - -Status of this Memo - - This document is an Internet-Draft and is in full conformance with - all provisions of Section 10 of RFC2026. - - Internet-Drafts are working documents of the Internet Engineering - Task Force (IETF), its areas, and its working groups. Note that other - groups may also distribute working documents as Internet-Drafts. - - Internet-Drafts are draft documents valid for a maximum of six months - and may be updated, replaced, or obsoleted by other documents at any - time. It is inappropriate to use Internet-Drafts as reference - material or to cite them other than as "work in progress." - - The list of current Internet-Drafts can be accessed at http:// - www.ietf.org/ietf/1id-abstracts.txt. - - The list of Internet-Draft Shadow Directories can be accessed at - http://www.ietf.org/shadow.html. - - This Internet-Draft will expire on March 31, 2004. - -Copyright Notice - - Copyright (C) The Internet Society (2003). All Rights Reserved. - -Abstract - - SSH is a protocol for secure remote login and other secure network - services over an insecure network. This document describes the - architecture of the SSH protocol, as well as the notation and - terminology used in SSH protocol documents. It also discusses the SSH - algorithm naming system that allows local extensions. The SSH - protocol consists of three major components: The Transport Layer - Protocol provides server authentication, confidentiality, and - integrity with perfect forward secrecy. The User Authentication - Protocol authenticates the client to the server. The Connection - Protocol multiplexes the encrypted tunnel into several logical - channels. Details of these protocols are described in separate - - - -Ylonen & Moffat Expires March 31, 2004 [Page 1] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - - documents. - -Table of Contents - - 1. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 3 - 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 - 3. Specification of Requirements . . . . . . . . . . . . . . . 3 - 4. Architecture . . . . . . . . . . . . . . . . . . . . . . . . 3 - 4.1 Host Keys . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 4.2 Extensibility . . . . . . . . . . . . . . . . . . . . . . . 5 - 4.3 Policy Issues . . . . . . . . . . . . . . . . . . . . . . . 5 - 4.4 Security Properties . . . . . . . . . . . . . . . . . . . . 6 - 4.5 Packet Size and Overhead . . . . . . . . . . . . . . . . . . 6 - 4.6 Localization and Character Set Support . . . . . . . . . . . 7 - 5. Data Type Representations Used in the SSH Protocols . . . . 8 - 6. Algorithm Naming . . . . . . . . . . . . . . . . . . . . . . 10 - 7. Message Numbers . . . . . . . . . . . . . . . . . . . . . . 11 - 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . 11 - 9. Security Considerations . . . . . . . . . . . . . . . . . . 12 - 9.1 Pseudo-Random Number Generation . . . . . . . . . . . . . . 12 - 9.2 Transport . . . . . . . . . . . . . . . . . . . . . . . . . 13 - 9.2.1 Confidentiality . . . . . . . . . . . . . . . . . . . . . . 13 - 9.2.2 Data Integrity . . . . . . . . . . . . . . . . . . . . . . . 16 - 9.2.3 Replay . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 - 9.2.4 Man-in-the-middle . . . . . . . . . . . . . . . . . . . . . 17 - 9.2.5 Denial-of-service . . . . . . . . . . . . . . . . . . . . . 19 - 9.2.6 Covert Channels . . . . . . . . . . . . . . . . . . . . . . 19 - 9.2.7 Forward Secrecy . . . . . . . . . . . . . . . . . . . . . . 20 - 9.3 Authentication Protocol . . . . . . . . . . . . . . . . . . 20 - 9.3.1 Weak Transport . . . . . . . . . . . . . . . . . . . . . . . 21 - 9.3.2 Debug messages . . . . . . . . . . . . . . . . . . . . . . . 21 - 9.3.3 Local security policy . . . . . . . . . . . . . . . . . . . 21 - 9.3.4 Public key authentication . . . . . . . . . . . . . . . . . 22 - 9.3.5 Password authentication . . . . . . . . . . . . . . . . . . 22 - 9.3.6 Host based authentication . . . . . . . . . . . . . . . . . 23 - 9.4 Connection protocol . . . . . . . . . . . . . . . . . . . . 23 - 9.4.1 End point security . . . . . . . . . . . . . . . . . . . . . 23 - 9.4.2 Proxy forwarding . . . . . . . . . . . . . . . . . . . . . . 23 - 9.4.3 X11 forwarding . . . . . . . . . . . . . . . . . . . . . . . 24 - Normative References . . . . . . . . . . . . . . . . . . . . 24 - Informative References . . . . . . . . . . . . . . . . . . . 25 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 27 - Intellectual Property and Copyright Statements . . . . . . . 28 - - - - - - - - -Ylonen & Moffat Expires March 31, 2004 [Page 2] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - -1. Contributors - - The major original contributors of this document were: Tatu Ylonen, - Tero Kivinen, Timo J. Rinne, Sami Lehtinen (all of SSH Communications - Security Corp), and Markku-Juhani O. Saarinen (University of - Jyvaskyla) - - The document editor is: [email protected]. Comments on this - internet draft should be sent to the IETF SECSH working group, - details at: http://ietf.org/html.charters/secsh-charter.html - -2. Introduction - - SSH is a protocol for secure remote login and other secure network - services over an insecure network. It consists of three major - components: - o The Transport Layer Protocol [SSH-TRANS] provides server - authentication, confidentiality, and integrity. It may optionally - also provide compression. The transport layer will typically be - run over a TCP/IP connection, but might also be used on top of any - other reliable data stream. - o The User Authentication Protocol [SSH-USERAUTH] authenticates the - client-side user to the server. It runs over the transport layer - protocol. - o The Connection Protocol [SSH-CONNECT] multiplexes the encrypted - tunnel into several logical channels. It runs over the user - authentication protocol. - - The client sends a service request once a secure transport layer - connection has been established. A second service request is sent - after user authentication is complete. This allows new protocols to - be defined and coexist with the protocols listed above. - - The connection protocol provides channels that can be used for a wide - range of purposes. Standard methods are provided for setting up - secure interactive shell sessions and for forwarding ("tunneling") - arbitrary TCP/IP ports and X11 connections. - -3. Specification of Requirements - - All documents related to the SSH protocols shall use the keywords - "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", - "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" to describe - requirements. They are to be interpreted as described in [RFC2119]. - -4. Architecture - - - - - -Ylonen & Moffat Expires March 31, 2004 [Page 3] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - -4.1 Host Keys - - Each server host SHOULD have a host key. Hosts MAY have multiple - host keys using multiple different algorithms. Multiple hosts MAY - share the same host key. If a host has keys at all, it MUST have at - least one key using each REQUIRED public key algorithm (DSS - [FIPS-186]). - - The server host key is used during key exchange to verify that the - client is really talking to the correct server. For this to be - possible, the client must have a priori knowledge of the server's - public host key. - - Two different trust models can be used: - o The client has a local database that associates each host name (as - typed by the user) with the corresponding public host key. This - method requires no centrally administered infrastructure, and no - third-party coordination. The downside is that the database of - name-to-key associations may become burdensome to maintain. - o The host name-to-key association is certified by some trusted - certification authority. The client only knows the CA root key, - and can verify the validity of all host keys certified by accepted - CAs. - - The second alternative eases the maintenance problem, since - ideally only a single CA key needs to be securely stored on the - client. On the other hand, each host key must be appropriately - certified by a central authority before authorization is possible. - Also, a lot of trust is placed on the central infrastructure. - - The protocol provides the option that the server name - host key - association is not checked when connecting to the host for the first - time. This allows communication without prior communication of host - keys or certification. The connection still provides protection - against passive listening; however, it becomes vulnerable to active - man-in-the-middle attacks. Implementations SHOULD NOT normally allow - such connections by default, as they pose a potential security - problem. However, as there is no widely deployed key infrastructure - available on the Internet yet, this option makes the protocol much - more usable during the transition time until such an infrastructure - emerges, while still providing a much higher level of security than - that offered by older solutions (e.g. telnet [RFC-854] and rlogin - [RFC-1282]). - - Implementations SHOULD try to make the best effort to check host - keys. An example of a possible strategy is to only accept a host key - without checking the first time a host is connected, save the key in - a local database, and compare against that key on all future - - - -Ylonen & Moffat Expires March 31, 2004 [Page 4] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - - connections to that host. - - Implementations MAY provide additional methods for verifying the - correctness of host keys, e.g. a hexadecimal fingerprint derived from - the SHA-1 hash of the public key. Such fingerprints can easily be - verified by using telephone or other external communication channels. - - All implementations SHOULD provide an option to not accept host keys - that cannot be verified. - - We believe that ease of use is critical to end-user acceptance of - security solutions, and no improvement in security is gained if the - new solutions are not used. Thus, providing the option not to check - the server host key is believed to improve the overall security of - the Internet, even though it reduces the security of the protocol in - configurations where it is allowed. - -4.2 Extensibility - - We believe that the protocol will evolve over time, and some - organizations will want to use their own encryption, authentication - and/or key exchange methods. Central registration of all extensions - is cumbersome, especially for experimental or classified features. - On the other hand, having no central registration leads to conflicts - in method identifiers, making interoperability difficult. - - We have chosen to identify algorithms, methods, formats, and - extension protocols with textual names that are of a specific format. - DNS names are used to create local namespaces where experimental or - classified extensions can be defined without fear of conflicts with - other implementations. - - One design goal has been to keep the base protocol as simple as - possible, and to require as few algorithms as possible. However, all - implementations MUST support a minimal set of algorithms to ensure - interoperability (this does not imply that the local policy on all - hosts would necessary allow these algorithms). The mandatory - algorithms are specified in the relevant protocol documents. - - Additional algorithms, methods, formats, and extension protocols can - be defined in separate drafts. See Section Algorithm Naming (Section - 6) for more information. - -4.3 Policy Issues - - The protocol allows full negotiation of encryption, integrity, key - exchange, compression, and public key algorithms and formats. - Encryption, integrity, public key, and compression algorithms can be - - - -Ylonen & Moffat Expires March 31, 2004 [Page 5] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - - different for each direction. - - The following policy issues SHOULD be addressed in the configuration - mechanisms of each implementation: - o Encryption, integrity, and compression algorithms, separately for - each direction. The policy MUST specify which is the preferred - algorithm (e.g. the first algorithm listed in each category). - o Public key algorithms and key exchange method to be used for host - authentication. The existence of trusted host keys for different - public key algorithms also affects this choice. - o The authentication methods that are to be required by the server - for each user. The server's policy MAY require multiple - authentication for some or all users. The required algorithms MAY - depend on the location where the user is trying to log in from. - o The operations that the user is allowed to perform using the - connection protocol. Some issues are related to security; for - example, the policy SHOULD NOT allow the server to start sessions - or run commands on the client machine, and MUST NOT allow - connections to the authentication agent unless forwarding such - connections has been requested. Other issues, such as which TCP/ - IP ports can be forwarded and by whom, are clearly issues of local - policy. Many of these issues may involve traversing or bypassing - firewalls, and are interrelated with the local security policy. - -4.4 Security Properties - - The primary goal of the SSH protocol is improved security on the - Internet. It attempts to do this in a way that is easy to deploy, - even at the cost of absolute security. - o All encryption, integrity, and public key algorithms used are - well-known, well-established algorithms. - o All algorithms are used with cryptographically sound key sizes - that are believed to provide protection against even the strongest - cryptanalytic attacks for decades. - o All algorithms are negotiated, and in case some algorithm is - broken, it is easy to switch to some other algorithm without - modifying the base protocol. - - Specific concessions were made to make wide-spread fast deployment - easier. The particular case where this comes up is verifying that - the server host key really belongs to the desired host; the protocol - allows the verification to be left out (but this is NOT RECOMMENDED). - This is believed to significantly improve usability in the short - term, until widespread Internet public key infrastructures emerge. - -4.5 Packet Size and Overhead - - Some readers will worry about the increase in packet size due to new - - - -Ylonen & Moffat Expires March 31, 2004 [Page 6] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - - headers, padding, and MAC. The minimum packet size is in the order - of 28 bytes (depending on negotiated algorithms). The increase is - negligible for large packets, but very significant for one-byte - packets (telnet-type sessions). There are, however, several factors - that make this a non-issue in almost all cases: - o The minimum size of a TCP/IP header is 32 bytes. Thus, the - increase is actually from 33 to 51 bytes (roughly). - o The minimum size of the data field of an Ethernet packet is 46 - bytes [RFC-894]. Thus, the increase is no more than 5 bytes. When - Ethernet headers are considered, the increase is less than 10 - percent. - o The total fraction of telnet-type data in the Internet is - negligible, even with increased packet sizes. - - The only environment where the packet size increase is likely to have - a significant effect is PPP [RFC-1134] over slow modem lines (PPP - compresses the TCP/IP headers, emphasizing the increase in packet - size). However, with modern modems, the time needed to transfer is in - the order of 2 milliseconds, which is a lot faster than people can - type. - - There are also issues related to the maximum packet size. To - minimize delays in screen updates, one does not want excessively - large packets for interactive sessions. The maximum packet size is - negotiated separately for each channel. - -4.6 Localization and Character Set Support - - For the most part, the SSH protocols do not directly pass text that - would be displayed to the user. However, there are some places where - such data might be passed. When applicable, the character set for the - data MUST be explicitly specified. In most places, ISO 10646 with - UTF-8 encoding is used [RFC-2279]. When applicable, a field is also - provided for a language tag [RFC-3066]. - - One big issue is the character set of the interactive session. There - is no clear solution, as different applications may display data in - different formats. Different types of terminal emulation may also be - employed in the client, and the character set to be used is - effectively determined by the terminal emulation. Thus, no place is - provided for directly specifying the character set or encoding for - terminal session data. However, the terminal emulation type (e.g. - "vt100") is transmitted to the remote site, and it implicitly - specifies the character set and encoding. Applications typically use - the terminal type to determine what character set they use, or the - character set is determined using some external means. The terminal - emulation may also allow configuring the default character set. In - any case, the character set for the terminal session is considered - - - -Ylonen & Moffat Expires March 31, 2004 [Page 7] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - - primarily a client local issue. - - Internal names used to identify algorithms or protocols are normally - never displayed to users, and must be in US-ASCII. - - The client and server user names are inherently constrained by what - the server is prepared to accept. They might, however, occasionally - be displayed in logs, reports, etc. They MUST be encoded using ISO - 10646 UTF-8, but other encodings may be required in some cases. It - is up to the server to decide how to map user names to accepted user - names. Straight bit-wise binary comparison is RECOMMENDED. - - For localization purposes, the protocol attempts to minimize the - number of textual messages transmitted. When present, such messages - typically relate to errors, debugging information, or some externally - configured data. For data that is normally displayed, it SHOULD be - possible to fetch a localized message instead of the transmitted - message by using a numerical code. The remaining messages SHOULD be - configurable. - -5. Data Type Representations Used in the SSH Protocols - byte - - A byte represents an arbitrary 8-bit value (octet) [RFC-1700]. - Fixed length data is sometimes represented as an array of bytes, - written byte[n], where n is the number of bytes in the array. - - boolean - - A boolean value is stored as a single byte. The value 0 - represents FALSE, and the value 1 represents TRUE. All non-zero - values MUST be interpreted as TRUE; however, applications MUST NOT - store values other than 0 and 1. - - uint32 - - Represents a 32-bit unsigned integer. Stored as four bytes in the - order of decreasing significance (network byte order). For - example, the value 699921578 (0x29b7f4aa) is stored as 29 b7 f4 - aa. - - uint64 - - Represents a 64-bit unsigned integer. Stored as eight bytes in - the order of decreasing significance (network byte order). - - - - - - -Ylonen & Moffat Expires March 31, 2004 [Page 8] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - - string - - Arbitrary length binary string. Strings are allowed to contain - arbitrary binary data, including null characters and 8-bit - characters. They are stored as a uint32 containing its length - (number of bytes that follow) and zero (= empty string) or more - bytes that are the value of the string. Terminating null - characters are not used. - - Strings are also used to store text. In that case, US-ASCII is - used for internal names, and ISO-10646 UTF-8 for text that might - be displayed to the user. The terminating null character SHOULD - NOT normally be stored in the string. - - For example, the US-ASCII string "testing" is represented as 00 00 - 00 07 t e s t i n g. The UTF8 mapping does not alter the encoding - of US-ASCII characters. - - mpint - - Represents multiple precision integers in two's complement format, - stored as a string, 8 bits per byte, MSB first. Negative numbers - have the value 1 as the most significant bit of the first byte of - the data partition. If the most significant bit would be set for a - positive number, the number MUST be preceded by a zero byte. - Unnecessary leading bytes with the value 0 or 255 MUST NOT be - included. The value zero MUST be stored as a string with zero - bytes of data. - - By convention, a number that is used in modular computations in - Z_n SHOULD be represented in the range 0 <= x < n. - - Examples: - value (hex) representation (hex) - --------------------------------------------------------------- - 0 00 00 00 00 - 9a378f9b2e332a7 00 00 00 08 09 a3 78 f9 b2 e3 32 a7 - 80 00 00 00 02 00 80 - -1234 00 00 00 02 ed cc - -deadbeef 00 00 00 05 ff 21 52 41 11 - - - - name-list - - A string containing a comma separated list of names. A name list - is represented as a uint32 containing its length (number of bytes - that follow) followed by a comma-separated list of zero or more - - - -Ylonen & Moffat Expires March 31, 2004 [Page 9] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - - names. A name MUST be non-zero length, and it MUST NOT contain a - comma (','). Context may impose additional restrictions on the - names; for example, the names in a list may have to be valid - algorithm identifier (see Algorithm Naming below), or [RFC-3066] - language tags. The order of the names in a list may or may not be - significant, also depending on the context where the list is is - used. Terminating NUL characters are not used, neither for the - individual names, nor for the list as a whole. - - Examples: - value representation (hex) - --------------------------------------- - (), the empty list 00 00 00 00 - ("zlib") 00 00 00 04 7a 6c 69 62 - ("zlib", "none") 00 00 00 09 7a 6c 69 62 2c 6e 6f 6e 65 - - - - -6. Algorithm Naming - - The SSH protocols refer to particular hash, encryption, integrity, - compression, and key exchange algorithms or protocols by names. - There are some standard algorithms that all implementations MUST - support. There are also algorithms that are defined in the protocol - specification but are OPTIONAL. Furthermore, it is expected that - some organizations will want to use their own algorithms. - - In this protocol, all algorithm identifiers MUST be printable - US-ASCII non-empty strings no longer than 64 characters. Names MUST - be case-sensitive. - - There are two formats for algorithm names: - o Names that do not contain an at-sign (@) are reserved to be - assigned by IETF consensus (RFCs). Examples include `3des-cbc', - `sha-1', `hmac-sha1', and `zlib' (the quotes are not part of the - name). Names of this format MUST NOT be used without first - registering them. Registered names MUST NOT contain an at-sign - (@) or a comma (,). - o Anyone can define additional algorithms by using names in the - format name@domainname, e.g. "[email protected]". The - format of the part preceding the at sign is not specified; it MUST - consist of US-ASCII characters except at-sign and comma. The part - following the at-sign MUST be a valid fully qualified internet - domain name [RFC-1034] controlled by the person or organization - defining the name. It is up to each domain how it manages its - local namespace. - - - - -Ylonen & Moffat Expires March 31, 2004 [Page 10] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - -7. Message Numbers - - SSH packets have message numbers in the range 1 to 255. These numbers - have been allocated as follows: - - - Transport layer protocol: - - 1 to 19 Transport layer generic (e.g. disconnect, ignore, debug, - etc.) - 20 to 29 Algorithm negotiation - 30 to 49 Key exchange method specific (numbers can be reused for - different authentication methods) - - User authentication protocol: - - 50 to 59 User authentication generic - 60 to 79 User authentication method specific (numbers can be - reused for different authentication methods) - - Connection protocol: - - 80 to 89 Connection protocol generic - 90 to 127 Channel related messages - - Reserved for client protocols: - - 128 to 191 Reserved - - Local extensions: - - 192 to 255 Local extensions - - - -8. IANA Considerations - - The initial state of the IANA registry is detailed in [SSH-NUMBERS]. - - Allocation of the following types of names in the SSH protocols is - assigned by IETF consensus: - o SSH encryption algorithm names, - o SSH MAC algorithm names, - o SSH public key algorithm names (public key algorithm also implies - encoding and signature/encryption capability), - o SSH key exchange method names, and - o SSH protocol (service) names. - - - - -Ylonen & Moffat Expires March 31, 2004 [Page 11] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - - These names MUST be printable US-ASCII strings, and MUST NOT contain - the characters at-sign ('@'), comma (','), or whitespace or control - characters (ASCII codes 32 or less). Names are case-sensitive, and - MUST NOT be longer than 64 characters. - - Names with the at-sign ('@') in them are allocated by the owner of - DNS name after the at-sign (hierarchical allocation in [RFC-2343]), - otherwise the same restrictions as above. - - Each category of names listed above has a separate namespace. - However, using the same name in multiple categories SHOULD be avoided - to minimize confusion. - - Message numbers (see Section Message Numbers (Section 7)) in the - range of 0..191 are allocated via IETF consensus; message numbers in - the 192..255 range (the "Local extensions" set) are reserved for - private use. - -9. Security Considerations - - In order to make the entire body of Security Considerations more - accessible, Security Considerations for the transport, - authentication, and connection documents have been gathered here. - - The transport protocol [1] provides a confidential channel over an - insecure network. It performs server host authentication, key - exchange, encryption, and integrity protection. It also derives a - unique session id that may be used by higher-level protocols. - - The authentication protocol [2] provides a suite of mechanisms which - can be used to authenticate the client user to the server. - Individual mechanisms specified in the in authentication protocol use - the session id provided by the transport protocol and/or depend on - the security and integrity guarantees of the transport protocol. - - The connection protocol [3] specifies a mechanism to multiplex - multiple streams [channels] of data over the confidential and - authenticated transport. It also specifies channels for accessing an - interactive shell, for 'proxy-forwarding' various external protocols - over the secure transport (including arbitrary TCP/IP protocols), and - for accessing secure 'subsystems' on the server host. - -9.1 Pseudo-Random Number Generation - - This protocol binds each session key to the session by including - random, session specific data in the hash used to produce session - keys. Special care should be taken to ensure that all of the random - numbers are of good quality. If the random data here (e.g., DH - - - -Ylonen & Moffat Expires March 31, 2004 [Page 12] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - - parameters) are pseudo-random then the pseudo-random number generator - should be cryptographically secure (i.e., its next output not easily - guessed even when knowing all previous outputs) and, furthermore, - proper entropy needs to be added to the pseudo-random number - generator. RFC 1750 [1750] offers suggestions for sources of random - numbers and entropy. Implementors should note the importance of - entropy and the well-meant, anecdotal warning about the difficulty in - properly implementing pseudo-random number generating functions. - - The amount of entropy available to a given client or server may - sometimes be less than what is required. In this case one must - either resort to pseudo-random number generation regardless of - insufficient entropy or refuse to run the protocol. The latter is - preferable. - -9.2 Transport - -9.2.1 Confidentiality - - It is beyond the scope of this document and the Secure Shell Working - Group to analyze or recommend specific ciphers other than the ones - which have been established and accepted within the industry. At the - time of this writing, ciphers commonly in use include 3DES, ARCFOUR, - twofish, serpent and blowfish. AES has been accepted by The - published as a US Federal Information Processing Standards [FIPS-197] - and the cryptographic community as being acceptable for this purpose - as well has accepted AES. As always, implementors and users should - check current literature to ensure that no recent vulnerabilities - have been found in ciphers used within products. Implementors should - also check to see which ciphers are considered to be relatively - stronger than others and should recommend their use to users over - relatively weaker ciphers. It would be considered good form for an - implementation to politely and unobtrusively notify a user that a - stronger cipher is available and should be used when a weaker one is - actively chosen. - - The "none" cipher is provided for debugging and SHOULD NOT be used - except for that purpose. It's cryptographic properties are - sufficiently described in RFC 2410, which will show that its use does - not meet the intent of this protocol. - - The relative merits of these and other ciphers may also be found in - current literature. Two references that may provide information on - the subject are [SCHNEIER] and [KAUFMAN,PERLMAN,SPECINER]. Both of - these describe the CBC mode of operation of certain ciphers and the - weakness of this scheme. Essentially, this mode is theoretically - vulnerable to chosen cipher-text attacks because of the high - predictability of the start of packet sequence. However, this attack - - - -Ylonen & Moffat Expires March 31, 2004 [Page 13] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - - is still deemed difficult and not considered fully practicable - especially if relatively longer block sizes are used. - - Additionally, another CBC mode attack may be mitigated through the - insertion of packets containing SSH_MSG_IGNORE. Without this - technique, a specific attack may be successful. For this attack - (commonly known as the Rogaway attack - [ROGAWAY],[DAI],[BELLARE,KOHNO,NAMPREMPRE]) to work, the attacker - would need to know the IV of the next block that is going to be - encrypted. In CBC mode that is the output of the encryption of the - previous block. If the attacker does not have any way to see the - packet yet (i.e it is in the internal buffers of the ssh - implementation or even in the kernel) then this attack will not work. - If the last packet has been sent out to the network (i.e the attacker - has access to it) then he can use the attack. - - In the optimal case an implementor would need to add an extra packet - only if the packet has been sent out onto the network and there are - no other packets waiting for transmission. Implementors may wish to - check to see if there are any unsent packets awaiting transmission, - but unfortunately it is not normally easy to obtain this information - from the kernel or buffers. If there are not, then a packet - containing SSH_MSG_IGNORE SHOULD be sent. If a new packet is added - to the stream every time the attacker knows the IV that is supposed - to be used for the next packet, then the attacker will not be able to - guess the correct IV, thus the attack will never be successfull. - - As an example, consider the following case: - - - Client Server - ------ ------ - TCP(seq=x, len=500) -> - contains Record 1 - - [500 ms passes, no ACK] - - TCP(seq=x, len=1000) -> - contains Records 1,2 - - ACK - - - 1. The Nagle algorithm + TCP retransmits mean that the two records - get coalesced into a single TCP segment - 2. Record 2 is *not* at the beginning of the TCP segment and never - will be, since it gets ACKed. - - - - -Ylonen & Moffat Expires March 31, 2004 [Page 14] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - - 3. Yet, the attack is possible because Record 1 has already been - seen. - - As this example indicates, it's totally unsafe to use the existence - of unflushed data in the TCP buffers proper as a guide to whether you - need an empty packet, since when you do the second write(), the - buffers will contain the un-ACKed Record 1. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Ylonen & Moffat Expires March 31, 2004 [Page 15] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - - On the other hand, it's perfectly safe to have the following - situation: - - - Client Server - ------ ------ - TCP(seq=x, len=500) -> - contains SSH_MSG_IGNORE - - TCP(seq=y, len=500) -> - contains Data - - Provided that the IV for second SSH Record is fixed after the data for - the Data packet is determined -i.e. you do: - read from user - encrypt null packet - encrypt data packet - - -9.2.2 Data Integrity - - This protocol does allow the Data Integrity mechanism to be disabled. - Implementors SHOULD be wary of exposing this feature for any purpose - other than debugging. Users and administrators SHOULD be explicitly - warned anytime the "none" MAC is enabled. - - So long as the "none" MAC is not used, this protocol provides data - integrity. - - Because MACs use a 32 bit sequence number, they might start to leak - information after 2**32 packets have been sent. However, following - the rekeying recommendations should prevent this attack. The - transport protocol [1] recommends rekeying after one gigabyte of - data, and the smallest possible packet is 16 bytes. Therefore, - rekeying SHOULD happen after 2**28 packets at the very most. - -9.2.3 Replay - - The use of a MAC other than 'none' provides integrity and - authentication. In addition, the transport protocol provides a - unique session identifier (bound in part to pseudo-random data that - is part of the algorithm and key exchange process) that can be used - by higher level protocols to bind data to a given session and prevent - replay of data from prior sessions. For example, the authentication - protocol uses this to prevent replay of signatures from previous - sessions. Because public key authentication exchanges are - cryptographically bound to the session (i.e., to the initial key - exchange) they cannot be successfully replayed in other sessions. - - - -Ylonen & Moffat Expires March 31, 2004 [Page 16] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - - Note that the session ID can be made public without harming the - security of the protocol. - - If two session happen to have the same session ID [hash of key - exchanges] then packets from one can be replayed against the other. - It must be stressed that the chances of such an occurrence are, - needless to say, minimal when using modern cryptographic methods. - This is all the more so true when specifying larger hash function - outputs and DH parameters. - - Replay detection using monotonically increasing sequence numbers as - input to the MAC, or HMAC in some cases, is described in [RFC2085] /> - [RFC2246], [RFC2743], [RFC1964], [RFC2025], and [RFC1510]. The - underlying construct is discussed in [RFC2104]. Essentially a - different sequence number in each packet ensures that at least this - one input to the MAC function will be unique and will provide a - nonrecurring MAC output that is not predictable to an attacker. If - the session stays active long enough, however, this sequence number - will wrap. This event may provide an attacker an opportunity to - replay a previously recorded packet with an identical sequence number - but only if the peers have not rekeyed since the transmission of the - first packet with that sequence number. If the peers have rekeyed, - then the replay will be detected as the MAC check will fail. For - this reason, it must be emphasized that peers MUST rekey before a - wrap of the sequence numbers. Naturally, if an attacker does attempt - to replay a captured packet before the peers have rekeyed, then the - receiver of the duplicate packet will not be able to validate the MAC - and it will be discarded. The reason that the MAC will fail is - because the receiver will formulate a MAC based upon the packet - contents, the shared secret, and the expected sequence number. Since - the replayed packet will not be using that expected sequence number - (the sequence number of the replayed packet will have already been - passed by the receiver) then the calculated MAC will not match the - MAC received with the packet. - -9.2.4 Man-in-the-middle - - This protocol makes no assumptions nor provisions for an - infrastructure or means for distributing the public keys of hosts. It - is expected that this protocol will sometimes be used without first - verifying the association between the server host key and the server - host name. Such usage is vulnerable to man-in-the-middle attacks. - This section describes this and encourages administrators and users - to understand the importance of verifying this association before any - session is initiated. - - There are three cases of man-in-the-middle attacks to consider. The - first is where an attacker places a device between the client and the - - - -Ylonen & Moffat Expires March 31, 2004 [Page 17] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - - server before the session is initiated. In this case, the attack - device is trying to mimic the legitimate server and will offer its - public key to the client when the client initiates a session. If it - were to offer the public key of the server, then it would not be able - to decrypt or sign the transmissions between the legitimate server - and the client unless it also had access to the private-key of the - host. The attack device will also, simultaneously to this, initiate - a session to the legitimate server masquerading itself as the client. - If the public key of the server had been securely distributed to the - client prior to that session initiation, the key offered to the - client by the attack device will not match the key stored on the - client. In that case, the user SHOULD be given a warning that the - offered host key does not match the host key cached on the client. - As described in Section 3.1 of [ARCH], the user may be free to accept - the new key and continue the session. It is RECOMMENDED that the - warning provide sufficient information to the user of the client - device so they may make an informed decision. If the user chooses to - continue the session with the stored public-key of the server (not - the public-key offered at the start of the session), then the session - specific data between the attacker and server will be different - between the client-to-attacker session and the attacker-to-server - sessions due to the randomness discussed above. From this, the - attacker will not be able to make this attack work since the attacker - will not be able to correctly sign packets containing this session - specific data from the server since he does not have the private key - of that server. - - The second case that should be considered is similar to the first - case in that it also happens at the time of connection but this case - points out the need for the secure distribution of server public - keys. If the server public keys are not securely distributed then - the client cannot know if it is talking to the intended server. An - attacker may use social engineering techniques to pass off server - keys to unsuspecting users and may then place a man-in-the-middle - attack device between the legitimate server and the clients. If this - is allowed to happen then the clients will form client-to-attacker - sessions and the attacker will form attacker-to-server sessions and - will be able to monitor and manipulate all of the traffic between the - clients and the legitimate servers. Server administrators are - encouraged to make host key fingerprints available for checking by - some means whose security does not rely on the integrity of the - actual host keys. Possible mechanisms are discussed in Section 3.1 - of [SSH-ARCH] and may also include secured Web pages, physical pieces - of paper, etc. Implementors SHOULD provide recommendations on how - best to do this with their implementation. Because the protocol is - extensible, future extensions to the protocol may provide better - mechanisms for dealing with the need to know the server's host key - before connecting. For example, making the host key fingerprint - - - -Ylonen & Moffat Expires March 31, 2004 [Page 18] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - - available through a secure DNS lookup, or using kerberos over gssapi - during key exchange to authenticate the server are possibilities. - - In the third man-in-the-middle case, attackers may attempt to - manipulate packets in transit between peers after the session has - been established. As described in the Replay part of this section, a - successful attack of this nature is very improbable. As in the - Replay section, this reasoning does assume that the MAC is secure and - that it is infeasible to construct inputs to a MAC algorithm to give - a known output. This is discussed in much greater detail in Section - 6 of RFC 2104. If the MAC algorithm has a vulnerability or is weak - enough, then the attacker may be able to specify certain inputs to - yield a known MAC. With that they may be able to alter the contents - of a packet in transit. Alternatively the attacker may be able to - exploit the algorithm vulnerability or weakness to find the shared - secret by reviewing the MACs from captured packets. In either of - those cases, an attacker could construct a packet or packets that - could be inserted into an SSH stream. To prevent that, implementors - are encouraged to utilize commonly accepted MAC algorithms and - administrators are encouraged to watch current literature and - discussions of cryptography to ensure that they are not using a MAC - algorithm that has a recently found vulnerability or weakness. - - In summary, the use of this protocol without a reliable association - of the binding between a host and its host keys is inherently - insecure and is NOT RECOMMENDED. It may however be necessary in - non-security critical environments, and will still provide protection - against passive attacks. Implementors of protocols and applications - running on top of this protocol should keep this possibility in mind. - -9.2.5 Denial-of-service - - This protocol is designed to be used over a reliable transport. If - transmission errors or message manipulation occur, the connection is - closed. The connection SHOULD be re-established if this occurs. - Denial of service attacks of this type ("wire cutter") are almost - impossible to avoid. - - In addition, this protocol is vulnerable to Denial of Service attacks - because an attacker can force the server to go through the CPU and - memory intensive tasks of connection setup and key exchange without - authenticating. Implementors SHOULD provide features that make this - more difficult. For example, only allowing connections from a subset - of IPs known to have valid users. - -9.2.6 Covert Channels - - The protocol was not designed to eliminate covert channels. For - - - -Ylonen & Moffat Expires March 31, 2004 [Page 19] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - - example, the padding, SSH_MSG_IGNORE messages, and several other - places in the protocol can be used to pass covert information, and - the recipient has no reliable way to verify whether such information - is being sent. - -9.2.7 Forward Secrecy - - It should be noted that the Diffie-Hellman key exchanges may provide - perfect forward secrecy (PFS). PFS is essentially defined as the - cryptographic property of a key-establishment protocol in which the - compromise of a session key or long-term private key after a given - session does not cause the compromise of any earlier session. [ANSI - T1.523-2001] SSHv2 sessions resulting from a key exchange using - diffie-hellman-group1-sha1 are secure even if private keying/ - authentication material is later revealed, but not if the session - keys are revealed. So, given this definition of PFS, SSHv2 does have - PFS. It is hoped that all other key exchange mechanisms proposed and - used in the future will also provide PFS. This property is not - commuted to any of the applications or protocols using SSH as a - transport however. The transport layer of SSH provides - confidentiality for password authentication and other methods that - rely on secret data. - - Of course, if the DH private parameters for the client and server are - revealed then the session key is revealed, but these items can be - thrown away after the key exchange completes. It's worth pointing - out that these items should not be allowed to end up on swap space - and that they should be erased from memory as soon as the key - exchange completes. - -9.3 Authentication Protocol - - The purpose of this protocol is to perform client user - authentication. It assumes that this run over a secure transport - layer protocol, which has already authenticated the server machine, - established an encrypted communications channel, and computed a - unique session identifier for this session. - - Several authentication methods with different security - characteristics are allowed. It is up to the server's local policy - to decide which methods (or combinations of methods) it is willing to - accept for each user. Authentication is no stronger than the weakest - combination allowed. - - The server may go into a "sleep" period after repeated unsuccessful - authentication attempts to make key search more difficult for - attackers. Care should be taken so that this doesn't become a - self-denial of service vector. - - - -Ylonen & Moffat Expires March 31, 2004 [Page 20] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - -9.3.1 Weak Transport - - If the transport layer does not provide confidentiality, - authentication methods that rely on secret data SHOULD be disabled. - If it does not provide strong integrity protection, requests to - change authentication data (e.g. a password change) SHOULD be - disabled to prevent an attacker from modifying the ciphertext - without being noticed, or rendering the new authentication data - unusable (denial of service). - - The assumption as stated above that the Authentication Protocol only - run over a secure transport that has previously authenticated the - server is very important to note. People deploying SSH are reminded - of the consequences of man-in-the-middle attacks if the client does - not have a very strong a priori association of the server with the - host key of that server. Specifically for the case of the - Authentication Protocol the client may form a session to a - man-in-the-middle attack device and divulge user credentials such as - their username and password. Even in the cases of authentication - where no user credentials are divulged, an attacker may still gain - information they shouldn't have by capturing key-strokes in much the - same way that a honeypot works. - -9.3.2 Debug messages - - Special care should be taken when designing debug messages. These - messages may reveal surprising amounts of information about the host - if not properly designed. Debug messages can be disabled (during - user authentication phase) if high security is required. - Administrators of host machines should make all attempts to - compartmentalize all event notification messages and protect them - from unwarranted observation. Developers should be aware of the - sensitive nature of some of the normal event messages and debug - messages and may want to provide guidance to administrators on ways - to keep this information away from unauthorized people. Developers - should consider minimizing the amount of sensitive information - obtainable by users during the authentication phase in accordance - with the local policies. For this reason, it is RECOMMENDED that - debug messages be initially disabled at the time of deployment and - require an active decision by an administrator to allow them to be - enabled. It is also RECOMMENDED that a message expressing this - concern be presented to the administrator of a system when the action - is taken to enable debugging messages. - -9.3.3 Local security policy - - Implementer MUST ensure that the credentials provided validate the - professed user and also MUST ensure that the local policy of the - - - -Ylonen & Moffat Expires March 31, 2004 [Page 21] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - - server permits the user the access requested. In particular, because - of the flexible nature of the SSH connection protocol, it may not be - possible to determine the local security policy, if any, that should - apply at the time of authentication because the kind of service being - requested is not clear at that instant. For example, local policy - might allow a user to access files on the server, but not start an - interactive shell. However, during the authentication protocol, it is - not known whether the user will be accessing files or attempting to - use an interactive shell, or even both. In any event, where local - security policy for the server host exists, it MUST be applied and - enforced correctly. - - Implementors are encouraged to provide a default local policy and - make its parameters known to administrators and users. At the - discretion of the implementors, this default policy may be along the - lines of 'anything goes' where there are no restrictions placed upon - users, or it may be along the lines of 'excessively restrictive' in - which case the administrators will have to actively make changes to - this policy to meet their needs. Alternatively, it may be some - attempt at providing something practical and immediately useful to - the administrators of the system so they don't have to put in much - effort to get SSH working. Whatever choice is made MUST be applied - and enforced as required above. - -9.3.4 Public key authentication - - The use of public-key authentication assumes that the client host has - not been compromised. It also assumes that the private-key of the - server host has not been compromised. - - This risk can be mitigated by the use of passphrases on private keys; - however, this is not an enforceable policy. The use of smartcards, - or other technology to make passphrases an enforceable policy is - suggested. - - The server could require both password and public-key authentication, - however, this requires the client to expose its password to the - server (see section on password authentication below.) - -9.3.5 Password authentication - - The password mechanism as specified in the authentication protocol - assumes that the server has not been compromised. If the server has - been compromised, using password authentication will reveal a valid - username / password combination to the attacker, which may lead to - further compromises. - - This vulnerability can be mitigated by using an alternative form of - - - -Ylonen & Moffat Expires March 31, 2004 [Page 22] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - - authentication. For example, public-key authentication makes no - assumptions about security on the server. - -9.3.6 Host based authentication - - Host based authentication assumes that the client has not been - compromised. There are no mitigating strategies, other than to use - host based authentication in combination with another authentication - method. - -9.4 Connection protocol - -9.4.1 End point security - - End point security is assumed by the connection protocol. If the - server has been compromised, any terminal sessions, port forwarding, - or systems accessed on the host are compromised. There are no - mitigating factors for this. - - If the client end point has been compromised, and the server fails to - stop the attacker at the authentication protocol, all services - exposed (either as subsystems or through forwarding) will be - vulnerable to attack. Implementors SHOULD provide mechanisms for - administrators to control which services are exposed to limit the - vulnerability of other services. - - These controls might include controlling which machines and ports can - be target in 'port-forwarding' operations, which users are allowed to - use interactive shell facilities, or which users are allowed to use - exposed subsystems. - -9.4.2 Proxy forwarding - - The SSH connection protocol allows for proxy forwarding of other - protocols such as SNMP, POP3, and HTTP. This may be a concern for - network administrators who wish to control the access of certain - applications by users located outside of their physical location. - Essentially, the forwarding of these protocols may violate site - specific security policies as they may be undetectably tunneled - through a firewall. Implementors SHOULD provide an administrative - mechanism to control the proxy forwarding functionality so that site - specific security policies may be upheld. - - In addition, a reverse proxy forwarding functionality is available, - which again can be used to bypass firewall controls. - - As indicated above, end-point security is assumed during proxy - forwarding operations. Failure of end-point security will compromise - - - -Ylonen & Moffat Expires March 31, 2004 [Page 23] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - - all data passed over proxy forwarding. - -9.4.3 X11 forwarding - - Another form of proxy forwarding provided by the ssh connection - protocol is the forwarding of the X11 protocol. If end-point - security has been compromised, X11 forwarding may allow attacks - against the X11 server. Users and administrators should, as a matter - of course, use appropriate X11 security mechanisms to prevent - unauthorized use of the X11 server. Implementors, administrators and - users who wish to further explore the security mechanisms of X11 are - invited to read [SCHEIFLER] and analyze previously reported problems - with the interactions between SSH forwarding and X11 in CERT - vulnerabilities VU#363181 and VU#118892 [CERT]. - - X11 display forwarding with SSH, by itself, is not sufficient to - correct well known problems with X11 security [VENEMA]. However, X11 - display forwarding in SSHv2 (or other, secure protocols), combined - with actual and pseudo-displays which accept connections only over - local IPC mechanisms authorized by permissions or ACLs, does correct - many X11 security problems as long as the "none" MAC is not used. It - is RECOMMENDED that X11 display implementations default to allowing - display opens only over local IPC. It is RECOMMENDED that SSHv2 - server implementations that support X11 forwarding default to - allowing display opens only over local IPC. On single-user systems - it might be reasonable to default to allowing local display opens - over TCP/IP. - - Implementors of the X11 forwarding protocol SHOULD implement the - magic cookie access checking spoofing mechanism as described in - [ssh-connect] as an additional mechanism to prevent unauthorized use - of the proxy. - -Normative References - - [SSH-ARCH] - Ylonen, T., "SSH Protocol Architecture", I-D - draft-ietf-architecture-15.txt, Oct 2003. - - [SSH-TRANS] - Ylonen, T., "SSH Transport Layer Protocol", I-D - draft-ietf-transport-17.txt, Oct 2003. - - [SSH-USERAUTH] - Ylonen, T., "SSH Authentication Protocol", I-D - draft-ietf-userauth-18.txt, Oct 2003. - - [SSH-CONNECT] - - - -Ylonen & Moffat Expires March 31, 2004 [Page 24] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - - Ylonen, T., "SSH Connection Protocol", I-D - draft-ietf-connect-18.txt, Oct 2003. - - [SSH-NUMBERS] - Lehtinen, S. and D. Moffat, "SSH Protocol Assigned - Numbers", I-D draft-ietf-secsh-assignednumbers-05.txt, Oct - 2003. - - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - -Informative References - - [FIPS-186] - Federal Information Processing Standards Publication, - "FIPS PUB 186, Digital Signature Standard", May 1994. - - [FIPS-197] - National Institue of Standards and Technology, "FIPS 197, - Specification for the Advanced Encryption Standard", - November 2001. - - [ANSI T1.523-2001] - American National Standards Insitute, Inc., "Telecom - Glossary 2000", February 2001. - - [SCHEIFLER] - Scheifler, R., "X Window System : The Complete Reference - to Xlib, X Protocol, Icccm, Xlfd, 3rd edition.", Digital - Press ISBN 1555580882, Feburary 1992. - - [RFC0854] Postel, J. and J. Reynolds, "Telnet Protocol - Specification", STD 8, RFC 854, May 1983. - - [RFC0894] Hornig, C., "Standard for the transmission of IP datagrams - over Ethernet networks", STD 41, RFC 894, April 1984. - - [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", - STD 13, RFC 1034, November 1987. - - [RFC1134] Perkins, D., "Point-to-Point Protocol: A proposal for - multi-protocol transmission of datagrams over - Point-to-Point links", RFC 1134, November 1989. - - [RFC1282] Kantor, B., "BSD Rlogin", RFC 1282, December 1991. - - [RFC1510] Kohl, J. and B. Neuman, "The Kerberos Network - Authentication Service (V5)", RFC 1510, September 1993. - - - -Ylonen & Moffat Expires March 31, 2004 [Page 25] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - - [RFC1700] Reynolds, J. and J. Postel, "Assigned Numbers", RFC 1700, - October 1994. - - [RFC1750] Eastlake, D., Crocker, S. and J. Schiller, "Randomness - Recommendations for Security", RFC 1750, December 1994. - - [RFC3066] Alvestrand, H., "Tags for the Identification of - Languages", BCP 47, RFC 3066, January 2001. - - [RFC1964] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC - 1964, June 1996. - - [RFC2025] Adams, C., "The Simple Public-Key GSS-API Mechanism - (SPKM)", RFC 2025, October 1996. - - [RFC2085] Oehler, M. and R. Glenn, "HMAC-MD5 IP Authentication with - Replay Prevention", RFC 2085, February 1997. - - [RFC2104] Krawczyk, H., Bellare, M. and R. Canetti, "HMAC: - Keyed-Hashing for Message Authentication", RFC 2104, - February 1997. - - [RFC2246] Dierks, T., Allen, C., Treese, W., Karlton, P., Freier, A. - and P. Kocher, "The TLS Protocol Version 1.0", RFC 2246, - January 1999. - - [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO - 10646", RFC 2279, January 1998. - - [RFC2410] Glenn, R. and S. Kent, "The NULL Encryption Algorithm and - Its Use With IPsec", RFC 2410, November 1998. - - [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an - IANA Considerations Section in RFCs", BCP 26, RFC 2434, - October 1998. - - [RFC2743] Linn, J., "Generic Security Service Application Program - Interface Version 2, Update 1", RFC 2743, January 2000. - - [SCHNEIER] - Schneier, B., "Applied Cryptography Second Edition: - protocols algorithms and source in code in C", 1996. - - [KAUFMAN,PERLMAN,SPECINER] - Kaufman, C., Perlman, R. and M. Speciner, "Network - Security: PRIVATE Communication in a PUBLIC World", 1995. - - [CERT] CERT Coordination Center, The., "http://www.cert.org/nav/ - - - -Ylonen & Moffat Expires March 31, 2004 [Page 26] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - - index_red.html". - - [VENEMA] Venema, W., "Murphy's Law and Computer Security", - Proceedings of 6th USENIX Security Symposium, San Jose CA - http://www.usenix.org/publications/library/proceedings/ - sec96/venema.html, July 1996. - - [ROGAWAY] Rogaway, P., "Problems with Proposed IP Cryptography", - Unpublished paper http://www.cs.ucdavis.edu/~rogaway/ - papers/draft-rogaway-ipsec-comments-00.txt, 1996. - - [DAI] Dai, W., "An attack against SSH2 protocol", Email to the - SECSH Working Group [email protected] ftp:// - ftp.ietf.org/ietf-mail-archive/secsh/2002-02.mail, Feb - 2002. - - [BELLARE,KOHNO,NAMPREMPRE] - Bellaire, M., Kohno, T. and C. Namprempre, "Authenticated - Encryption in SSH: Fixing the SSH Binary Packet Protocol", - , Sept 2002. - - -Authors' Addresses - - Tatu Ylonen - SSH Communications Security Corp - Fredrikinkatu 42 - HELSINKI FIN-00100 - Finland - - EMail: [email protected] - - - Darren J. Moffat (editor) - Sun Microsystems, Inc - 17 Network Circle - Menlo Park CA 94025 - USA - - EMail: [email protected] - - - - - - - - - - - -Ylonen & Moffat Expires March 31, 2004 [Page 27] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - -Intellectual Property Statement - - The IETF takes no position regarding the validity or scope of any - intellectual property 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; neither does it represent that it - has made any effort to identify any such rights. Information on the - IETF's procedures with respect to rights in standards-track and - standards-related documentation can be found in BCP-11. Copies of - claims of rights made available for publication 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 implementors or users of this specification can - be obtained from the IETF Secretariat. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights which may cover technology that may be required to practice - this standard. Please address the information to the IETF Executive - Director. - - The IETF has been notified of intellectual property rights claimed in - regard to some or all of the specification contained in this - document. For more information consult the online list of claimed - rights. - - -Full Copyright Statement - - Copyright (C) The Internet Society (2003). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assignees. - - - -Ylonen & Moffat Expires March 31, 2004 [Page 28] - -Internet-Draft SSH Protocol Architecture Oct 2003 - - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS 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. - - -Acknowledgment - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Ylonen & Moffat Expires March 31, 2004 [Page 29]
\ No newline at end of file diff --git a/lib/ssh/doc/standard/draft-ietf-secsh-connect-18.2.ps b/lib/ssh/doc/standard/draft-ietf-secsh-connect-18.2.ps deleted file mode 100644 index 7a386724c2..0000000000 --- a/lib/ssh/doc/standard/draft-ietf-secsh-connect-18.2.ps +++ /dev/null @@ -1,2557 +0,0 @@ -%!PS-Adobe-3.0 -%%BoundingBox: 75 0 595 747 -%%Title: Enscript Output -%%For: Magnus Thoang -%%Creator: GNU enscript 1.6.1 -%%CreationDate: Fri Oct 31 13:33:02 2003 -%%Orientation: Portrait -%%Pages: 11 0 -%%DocumentMedia: A4 595 842 0 () () -%%DocumentNeededResources: (atend) -%%EndComments -%%BeginProlog -%%BeginProcSet: PStoPS 1 15 -userdict begin -[/showpage/erasepage/copypage]{dup where{pop dup load - type/operatortype eq{1 array cvx dup 0 3 index cvx put - bind def}{pop}ifelse}{pop}ifelse}forall -[/letter/legal/executivepage/a4/a4small/b5/com10envelope - /monarchenvelope/c5envelope/dlenvelope/lettersmall/note - /folio/quarto/a5]{dup where{dup wcheck{exch{}put} - {pop{}def}ifelse}{pop}ifelse}forall -/setpagedevice {pop}bind 1 index where{dup wcheck{3 1 roll put} - {pop def}ifelse}{def}ifelse -/PStoPSmatrix matrix currentmatrix def -/PStoPSxform matrix def/PStoPSclip{clippath}def -/defaultmatrix{PStoPSmatrix exch PStoPSxform exch concatmatrix}bind def -/initmatrix{matrix defaultmatrix setmatrix}bind def -/initclip[{matrix currentmatrix PStoPSmatrix setmatrix - [{currentpoint}stopped{$error/newerror false put{newpath}} - {/newpath cvx 3 1 roll/moveto cvx 4 array astore cvx}ifelse] - {[/newpath cvx{/moveto cvx}{/lineto cvx} - {/curveto cvx}{/closepath cvx}pathforall]cvx exch pop} - stopped{$error/errorname get/invalidaccess eq{cleartomark - $error/newerror false put cvx exec}{stop}ifelse}if}bind aload pop - /initclip dup load dup type dup/operatortype eq{pop exch pop} - {dup/arraytype eq exch/packedarraytype eq or - {dup xcheck{exch pop aload pop}{pop cvx}ifelse} - {pop cvx}ifelse}ifelse - {newpath PStoPSclip clip newpath exec setmatrix} bind aload pop]cvx def -/initgraphics{initmatrix newpath initclip 1 setlinewidth - 0 setlinecap 0 setlinejoin []0 setdash 0 setgray - 10 setmiterlimit}bind def -end -%%EndProcSet -%%BeginResource: procset Enscript-Prolog 1.6 1 -% -% Procedures. -% - -/_S { % save current state - /_s save def -} def -/_R { % restore from saved state - _s restore -} def - -/S { % showpage protecting gstate - gsave - showpage - grestore -} bind def - -/MF { % fontname newfontname -> - make a new encoded font - /newfontname exch def - /fontname exch def - - /fontdict fontname findfont def - /newfont fontdict maxlength dict def - - fontdict { - exch - dup /FID eq { - % skip FID pair - pop pop - } { - % copy to the new font dictionary - exch newfont 3 1 roll put - } ifelse - } forall - - newfont /FontName newfontname put - - % insert only valid encoding vectors - encoding_vector length 256 eq { - newfont /Encoding encoding_vector put - } if - - newfontname newfont definefont pop -} def - -/SF { % fontname width height -> - set a new font - /height exch def - /width exch def - - findfont - [width 0 0 height 0 0] makefont setfont -} def - -/SUF { % fontname width height -> - set a new user font - /height exch def - /width exch def - - /F-gs-user-font MF - /F-gs-user-font width height SF -} def - -/M {moveto} bind def -/s {show} bind def - -/Box { % x y w h -> - define box path - /d_h exch def /d_w exch def /d_y exch def /d_x exch def - d_x d_y moveto - d_w 0 rlineto - 0 d_h rlineto - d_w neg 0 rlineto - closepath -} def - -/bgs { % x y height blskip gray str -> - show string with bg color - /str exch def - /gray exch def - /blskip exch def - /height exch def - /y exch def - /x exch def - - gsave - x y blskip sub str stringwidth pop height Box - gray setgray - fill - grestore - x y M str s -} def - -% Highlight bars. -/highlight_bars { % nlines lineheight output_y_margin gray -> - - gsave - setgray - /ymarg exch def - /lineheight exch def - /nlines exch def - - % This 2 is just a magic number to sync highlight lines to text. - 0 d_header_y ymarg sub 2 sub translate - - /cw d_output_w cols div def - /nrows d_output_h ymarg 2 mul sub lineheight div cvi def - - % for each column - 0 1 cols 1 sub { - cw mul /xp exch def - - % for each rows - 0 1 nrows 1 sub { - /rn exch def - rn lineheight mul neg /yp exch def - rn nlines idiv 2 mod 0 eq { - % Draw highlight bar. 4 is just a magic indentation. - xp 4 add yp cw 8 sub lineheight neg Box fill - } if - } for - } for - - grestore -} def - -% Line highlight bar. -/line_highlight { % x y width height gray -> - - gsave - /gray exch def - Box gray setgray fill - grestore -} def - -% Column separator lines. -/column_lines { - gsave - .1 setlinewidth - 0 d_footer_h translate - /cw d_output_w cols div def - 1 1 cols 1 sub { - cw mul 0 moveto - 0 d_output_h rlineto stroke - } for - grestore -} def - -% Column borders. -/column_borders { - gsave - .1 setlinewidth - 0 d_footer_h moveto - 0 d_output_h rlineto - d_output_w 0 rlineto - 0 d_output_h neg rlineto - closepath stroke - grestore -} def - -% Do the actual underlay drawing -/draw_underlay { - ul_style 0 eq { - ul_str true charpath stroke - } { - ul_str show - } ifelse -} def - -% Underlay -/underlay { % - -> - - gsave - 0 d_page_h translate - d_page_h neg d_page_w atan rotate - - ul_gray setgray - ul_font setfont - /dw d_page_h dup mul d_page_w dup mul add sqrt def - ul_str stringwidth pop dw exch sub 2 div ul_h_ptsize -2 div moveto - draw_underlay - grestore -} def - -/user_underlay { % - -> - - gsave - ul_x ul_y translate - ul_angle rotate - ul_gray setgray - ul_font setfont - 0 0 ul_h_ptsize 2 div sub moveto - draw_underlay - grestore -} def - -% Page prefeed -/page_prefeed { % bool -> - - statusdict /prefeed known { - statusdict exch /prefeed exch put - } { - pop - } ifelse -} def - -% Wrapped line markers -/wrapped_line_mark { % x y charwith charheight type -> - - /type exch def - /h exch def - /w exch def - /y exch def - /x exch def - - type 2 eq { - % Black boxes (like TeX does) - gsave - 0 setlinewidth - x w 4 div add y M - 0 h rlineto w 2 div 0 rlineto 0 h neg rlineto - closepath fill - grestore - } { - type 3 eq { - % Small arrows - gsave - .2 setlinewidth - x w 2 div add y h 2 div add M - w 4 div 0 rlineto - x w 4 div add y lineto stroke - - x w 4 div add w 8 div add y h 4 div add M - x w 4 div add y lineto - w 4 div h 8 div rlineto stroke - grestore - } { - % do nothing - } ifelse - } ifelse -} def - -% EPSF import. - -/BeginEPSF { - /b4_Inc_state save def % Save state for cleanup - /dict_count countdictstack def % Count objects on dict stack - /op_count count 1 sub def % Count objects on operand stack - userdict begin - /showpage { } def - 0 setgray 0 setlinecap - 1 setlinewidth 0 setlinejoin - 10 setmiterlimit [ ] 0 setdash newpath - /languagelevel where { - pop languagelevel - 1 ne { - false setstrokeadjust false setoverprint - } if - } if -} bind def - -/EndEPSF { - count op_count sub { pos } repeat % Clean up stacks - countdictstack dict_count sub { end } repeat - b4_Inc_state restore -} bind def - -% Check PostScript language level. -/languagelevel where { - pop /gs_languagelevel languagelevel def -} { - /gs_languagelevel 1 def -} ifelse -%%EndResource -%%BeginResource: procset Enscript-Encoding-88591 1.6 1 -/encoding_vector [ -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/space /exclam /quotedbl /numbersign -/dollar /percent /ampersand /quoteright -/parenleft /parenright /asterisk /plus -/comma /hyphen /period /slash -/zero /one /two /three -/four /five /six /seven -/eight /nine /colon /semicolon -/less /equal /greater /question -/at /A /B /C -/D /E /F /G -/H /I /J /K -/L /M /N /O -/P /Q /R /S -/T /U /V /W -/X /Y /Z /bracketleft -/backslash /bracketright /asciicircum /underscore -/quoteleft /a /b /c -/d /e /f /g -/h /i /j /k -/l /m /n /o -/p /q /r /s -/t /u /v /w -/x /y /z /braceleft -/bar /braceright /tilde /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/space /exclamdown /cent /sterling -/currency /yen /brokenbar /section -/dieresis /copyright /ordfeminine /guillemotleft -/logicalnot /hyphen /registered /macron -/degree /plusminus /twosuperior /threesuperior -/acute /mu /paragraph /bullet -/cedilla /onesuperior /ordmasculine /guillemotright -/onequarter /onehalf /threequarters /questiondown -/Agrave /Aacute /Acircumflex /Atilde -/Adieresis /Aring /AE /Ccedilla -/Egrave /Eacute /Ecircumflex /Edieresis -/Igrave /Iacute /Icircumflex /Idieresis -/Eth /Ntilde /Ograve /Oacute -/Ocircumflex /Otilde /Odieresis /multiply -/Oslash /Ugrave /Uacute /Ucircumflex -/Udieresis /Yacute /Thorn /germandbls -/agrave /aacute /acircumflex /atilde -/adieresis /aring /ae /ccedilla -/egrave /eacute /ecircumflex /edieresis -/igrave /iacute /icircumflex /idieresis -/eth /ntilde /ograve /oacute -/ocircumflex /otilde /odieresis /divide -/oslash /ugrave /uacute /ucircumflex -/udieresis /yacute /thorn /ydieresis -] def -%%EndResource -%%EndProlog -%%BeginSetup -%%IncludeResource: font Courier-Bold -%%IncludeResource: font Courier -/HFpt_w 10 def -/HFpt_h 10 def -/Courier-Bold /HF-gs-font MF -/HF /HF-gs-font findfont [HFpt_w 0 0 HFpt_h 0 0] makefont def -/Courier /F-gs-font MF -/F-gs-font 10 10 SF -/#copies 1 def -/d_page_w 520 def -/d_page_h 747 def -/d_header_x 0 def -/d_header_y 747 def -/d_header_w 520 def -/d_header_h 0 def -/d_footer_x 0 def -/d_footer_y 0 def -/d_footer_w 520 def -/d_footer_h 0 def -/d_output_w 520 def -/d_output_h 747 def -/cols 1 def -userdict/PStoPSxform PStoPSmatrix matrix currentmatrix - matrix invertmatrix matrix concatmatrix - matrix invertmatrix put -%%EndSetup -%%Page: (0,1) 1 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 1 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 701 M -(Network Working Group T. Ylonen) s -5 690 M -(Internet-Draft SSH Communications Security Corp) s -5 679 M -(Expires: March 31, 2004 D. Moffat, Editor, Ed.) s -5 668 M -( Sun Microsystems, Inc) s -5 657 M -( Oct 2003) s -5 624 M -( SSH Connection Protocol) s -5 613 M -( draft-ietf-secsh-connect-18.txt) s -5 591 M -(Status of this Memo) s -5 569 M -( This document is an Internet-Draft and is in full conformance with) s -5 558 M -( all provisions of Section 10 of RFC2026.) s -5 536 M -( Internet-Drafts are working documents of the Internet Engineering) s -5 525 M -( Task Force \(IETF\), its areas, and its working groups. Note that other) s -5 514 M -( groups may also distribute working documents as Internet-Drafts.) s -5 492 M -( Internet-Drafts are draft documents valid for a maximum of six months) s -5 481 M -( and may be updated, replaced, or obsoleted by other documents at any) s -5 470 M -( time. It is inappropriate to use Internet-Drafts as reference) s -5 459 M -( material or to cite them other than as "work in progress.") s -5 437 M -( The list of current Internet-Drafts can be accessed at http://) s -5 426 M -( www.ietf.org/ietf/1id-abstracts.txt.) s -5 404 M -( The list of Internet-Draft Shadow Directories can be accessed at) s -5 393 M -( http://www.ietf.org/shadow.html.) s -5 371 M -( This Internet-Draft will expire on March 31, 2004.) s -5 349 M -(Copyright Notice) s -5 327 M -( Copyright \(C\) The Internet Society \(2003\). All Rights Reserved.) s -5 305 M -(Abstract) s -5 283 M -( SSH is a protocol for secure remote login and other secure network) s -5 272 M -( services over an insecure network.) s -5 250 M -( This document describes the SSH Connection Protocol. It provides) s -5 239 M -( interactive login sessions, remote execution of commands, forwarded) s -5 228 M -( TCP/IP connections, and forwarded X11 connections. All of these) s -5 217 M -( channels are multiplexed into a single encrypted tunnel.) s -5 195 M -( The SSH Connection Protocol has been designed to run on top of the) s -5 184 M -( SSH transport layer and user authentication protocols.) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 1]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 2 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Connection Protocol Oct 2003) s -5 690 M -(Table of Contents) s -5 668 M -( 1. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 3) s -5 657 M -( 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3) s -5 646 M -( 3. Conventions Used in This Document . . . . . . . . . . . . . 3) s -5 635 M -( 4. Global Requests . . . . . . . . . . . . . . . . . . . . . . 3) s -5 624 M -( 5. Channel Mechanism . . . . . . . . . . . . . . . . . . . . . 4) s -5 613 M -( 5.1 Opening a Channel . . . . . . . . . . . . . . . . . . . . . 4) s -5 602 M -( 5.2 Data Transfer . . . . . . . . . . . . . . . . . . . . . . . 5) s -5 591 M -( 5.3 Closing a Channel . . . . . . . . . . . . . . . . . . . . . 6) s -5 580 M -( 5.4 Channel-Specific Requests . . . . . . . . . . . . . . . . . 7) s -5 569 M -( 6. Interactive Sessions . . . . . . . . . . . . . . . . . . . . 8) s -5 558 M -( 6.1 Opening a Session . . . . . . . . . . . . . . . . . . . . . 8) s -5 547 M -( 6.2 Requesting a Pseudo-Terminal . . . . . . . . . . . . . . . . 8) s -5 536 M -( 6.3 X11 Forwarding . . . . . . . . . . . . . . . . . . . . . . . 9) s -5 525 M -( 6.3.1 Requesting X11 Forwarding . . . . . . . . . . . . . . . . . 9) s -5 514 M -( 6.3.2 X11 Channels . . . . . . . . . . . . . . . . . . . . . . . . 10) s -5 503 M -( 6.4 Environment Variable Passing . . . . . . . . . . . . . . . . 10) s -5 492 M -( 6.5 Starting a Shell or a Command . . . . . . . . . . . . . . . 10) s -5 481 M -( 6.6 Session Data Transfer . . . . . . . . . . . . . . . . . . . 11) s -5 470 M -( 6.7 Window Dimension Change Message . . . . . . . . . . . . . . 12) s -5 459 M -( 6.8 Local Flow Control . . . . . . . . . . . . . . . . . . . . . 12) s -5 448 M -( 6.9 Signals . . . . . . . . . . . . . . . . . . . . . . . . . . 12) s -5 437 M -( 6.10 Returning Exit Status . . . . . . . . . . . . . . . . . . . 13) s -5 426 M -( 7. TCP/IP Port Forwarding . . . . . . . . . . . . . . . . . . . 14) s -5 415 M -( 7.1 Requesting Port Forwarding . . . . . . . . . . . . . . . . . 14) s -5 404 M -( 7.2 TCP/IP Forwarding Channels . . . . . . . . . . . . . . . . . 15) s -5 393 M -( 8. Encoding of Terminal Modes . . . . . . . . . . . . . . . . . 16) s -5 382 M -( 9. Summary of Message Numbers . . . . . . . . . . . . . . . . . 18) s -5 371 M -( 10. Security Considerations . . . . . . . . . . . . . . . . . . 18) s -5 360 M -( 11. iana cONSiderations . . . . . . . . . . . . . . . . . . . . 19) s -5 349 M -( 12. Intellectual Property . . . . . . . . . . . . . . . . . . . 19) s -5 338 M -( Normative References . . . . . . . . . . . . . . . . . . . . 19) s -5 327 M -( Informative References . . . . . . . . . . . . . . . . . . . 20) s -5 316 M -( Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 20) s -5 305 M -( Intellectual Property and Copyright Statements . . . . . . . 21) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 2]) s -_R -S -PStoPSsaved restore -%%Page: (2,3) 2 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 3 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Connection Protocol Oct 2003) s -5 690 M -(1. Contributors) s -5 668 M -( The major original contributors of this document were: Tatu Ylonen,) s -5 657 M -( Tero Kivinen, Timo J. Rinne, Sami Lehtinen \(all of SSH Communications) s -5 646 M -( Security Corp\), and Markku-Juhani O. Saarinen \(University of) s -5 635 M -( Jyvaskyla\)) s -5 613 M -( The document editor is: [email protected]. Comments on this) s -5 602 M -( internet draft should be sent to the IETF SECSH working group,) s -5 591 M -( details at: http://ietf.org/html.charters/secsh-charter.html) s -5 569 M -(2. Introduction) s -5 547 M -( The SSH Connection Protocol has been designed to run on top of the) s -5 536 M -( SSH transport layer and user authentication protocols. It provides) s -5 525 M -( interactive login sessions, remote execution of commands, forwarded) s -5 514 M -( TCP/IP connections, and forwarded X11 connections. The service name) s -5 503 M -( for this protocol is "ssh-connection".) s -5 481 M -( This document should be read only after reading the SSH architecture) s -5 470 M -( document [SSH-ARCH]. This document freely uses terminology and) s -5 459 M -( notation from the architecture document without reference or further) s -5 448 M -( explanation.) s -5 426 M -(3. Conventions Used in This Document) s -5 404 M -( The keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT",) s -5 393 M -( and "MAY" that appear in this document are to be interpreted as) s -5 382 M -( described in [RFC2119].) s -5 360 M -( The used data types and terminology are specified in the architecture) s -5 349 M -( document [SSH-ARCH].) s -5 327 M -( The architecture document also discusses the algorithm naming) s -5 316 M -( conventions that MUST be used with the SSH protocols.) s -5 294 M -(4. Global Requests) s -5 272 M -( There are several kinds of requests that affect the state of the) s -5 261 M -( remote end "globally", independent of any channels. An example is a) s -5 250 M -( request to start TCP/IP forwarding for a specific port. All such) s -5 239 M -( requests use the following format.) s -5 217 M -( byte SSH_MSG_GLOBAL_REQUEST) s -5 206 M -( string request name \(restricted to US-ASCII\)) s -5 195 M -( boolean want reply) s -5 184 M -( ... request-specific data follows) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 3]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 4 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Connection Protocol Oct 2003) s -5 690 M -( Request names follow the DNS extensibility naming convention outlined) s -5 679 M -( in [SSH-ARCH].) s -5 657 M -( The recipient will respond to this message with) s -5 646 M -( SSH_MSG_REQUEST_SUCCESS or SSH_MSG_REQUEST_FAILURE if `want reply' is) s -5 635 M -( TRUE.) s -5 613 M -( byte SSH_MSG_REQUEST_SUCCESS) s -5 602 M -( ..... response specific data) s -5 580 M -( Usually the response specific data is non-existent.) s -5 558 M -( If the recipient does not recognize or support the request, it simply) s -5 547 M -( responds with SSH_MSG_REQUEST_FAILURE.) s -5 525 M -( byte SSH_MSG_REQUEST_FAILURE) s -5 492 M -(5. Channel Mechanism) s -5 470 M -( All terminal sessions, forwarded connections, etc. are channels.) s -5 459 M -( Either side may open a channel. Multiple channels are multiplexed) s -5 448 M -( into a single connection.) s -5 426 M -( Channels are identified by numbers at each end. The number referring) s -5 415 M -( to a channel may be different on each side. Requests to open a) s -5 404 M -( channel contain the sender's channel number. Any other) s -5 393 M -( channel-related messages contain the recipient's channel number for) s -5 382 M -( the channel.) s -5 360 M -( Channels are flow-controlled. No data may be sent to a channel until) s -5 349 M -( a message is received to indicate that window space is available.) s -5 327 M -(5.1 Opening a Channel) s -5 305 M -( When either side wishes to open a new channel, it allocates a local) s -5 294 M -( number for the channel. It then sends the following message to the) s -5 283 M -( other side, and includes the local channel number and initial window) s -5 272 M -( size in the message.) s -5 250 M -( byte SSH_MSG_CHANNEL_OPEN) s -5 239 M -( string channel type \(restricted to US-ASCII\)) s -5 228 M -( uint32 sender channel) s -5 217 M -( uint32 initial window size) s -5 206 M -( uint32 maximum packet size) s -5 195 M -( ... channel type specific data follows) s -5 173 M -( The channel type is a name as described in the SSH architecture) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 4]) s -_R -S -PStoPSsaved restore -%%Page: (4,5) 3 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 5 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Connection Protocol Oct 2003) s -5 690 M -( document, with similar extension mechanisms. `sender channel' is a) s -5 679 M -( local identifier for the channel used by the sender of this message.) s -5 668 M -( `initial window size' specifies how many bytes of channel data can be) s -5 657 M -( sent to the sender of this message without adjusting the window.) s -5 646 M -( `Maximum packet size' specifies the maximum size of an individual) s -5 635 M -( data packet that can be sent to the sender \(for example, one might) s -5 624 M -( want to use smaller packets for interactive connections to get better) s -5 613 M -( interactive response on slow links\).) s -5 591 M -( The remote side then decides whether it can open the channel, and) s -5 580 M -( responds with either) s -5 558 M -( byte SSH_MSG_CHANNEL_OPEN_CONFIRMATION) s -5 547 M -( uint32 recipient channel) s -5 536 M -( uint32 sender channel) s -5 525 M -( uint32 initial window size) s -5 514 M -( uint32 maximum packet size) s -5 503 M -( ... channel type specific data follows) s -5 481 M -( where `recipient channel' is the channel number given in the original) s -5 470 M -( open request, and `sender channel' is the channel number allocated by) s -5 459 M -( the other side, or) s -5 437 M -( byte SSH_MSG_CHANNEL_OPEN_FAILURE) s -5 426 M -( uint32 recipient channel) s -5 415 M -( uint32 reason code) s -5 404 M -( string additional textual information \(ISO-10646 UTF-8 [RFC2279]\)) s -5 393 M -( string language tag \(as defined in [RFC3066]\)) s -5 371 M -( If the recipient of the SSH_MSG_CHANNEL_OPEN message does not support) s -5 360 M -( the specified channel type, it simply responds with) s -5 349 M -( SSH_MSG_CHANNEL_OPEN_FAILURE. The client MAY show the additional) s -5 338 M -( information to the user. If this is done, the client software should) s -5 327 M -( take the precautions discussed in [SSH-ARCH].) s -5 305 M -( The following reason codes are defined:) s -5 283 M -( #define SSH_OPEN_ADMINISTRATIVELY_PROHIBITED 1) s -5 272 M -( #define SSH_OPEN_CONNECT_FAILED 2) s -5 261 M -( #define SSH_OPEN_UNKNOWN_CHANNEL_TYPE 3) s -5 250 M -( #define SSH_OPEN_RESOURCE_SHORTAGE 4) s -5 217 M -(5.2 Data Transfer) s -5 195 M -( The window size specifies how many bytes the other party can send) s -5 184 M -( before it must wait for the window to be adjusted. Both parties use) s -5 173 M -( the following message to adjust the window.) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 5]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 6 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Connection Protocol Oct 2003) s -5 690 M -( byte SSH_MSG_CHANNEL_WINDOW_ADJUST) s -5 679 M -( uint32 recipient channel) s -5 668 M -( uint32 bytes to add) s -5 646 M -( After receiving this message, the recipient MAY send the given number) s -5 635 M -( of bytes more than it was previously allowed to send; the window size) s -5 624 M -( is incremented.) s -5 602 M -( Data transfer is done with messages of the following type.) s -5 580 M -( byte SSH_MSG_CHANNEL_DATA) s -5 569 M -( uint32 recipient channel) s -5 558 M -( string data) s -5 536 M -( The maximum amount of data allowed is the current window size. The) s -5 525 M -( window size is decremented by the amount of data sent. Both parties) s -5 514 M -( MAY ignore all extra data sent after the allowed window is empty.) s -5 492 M -( Additionally, some channels can transfer several types of data. An) s -5 481 M -( example of this is stderr data from interactive sessions. Such data) s -5 470 M -( can be passed with SSH_MSG_CHANNEL_EXTENDED_DATA messages, where a) s -5 459 M -( separate integer specifies the type of the data. The available types) s -5 448 M -( and their interpretation depend on the type of the channel.) s -5 426 M -( byte SSH_MSG_CHANNEL_EXTENDED_DATA) s -5 415 M -( uint32 recipient_channel) s -5 404 M -( uint32 data_type_code) s -5 393 M -( string data) s -5 371 M -( Data sent with these messages consumes the same window as ordinary) s -5 360 M -( data.) s -5 338 M -( Currently, only the following type is defined.) s -5 316 M -( #define SSH_EXTENDED_DATA_STDERR 1) s -5 283 M -(5.3 Closing a Channel) s -5 261 M -( When a party will no longer send more data to a channel, it SHOULD) s -5 250 M -( send SSH_MSG_CHANNEL_EOF.) s -5 228 M -( byte SSH_MSG_CHANNEL_EOF) s -5 217 M -( uint32 recipient_channel) s -5 195 M -( No explicit response is sent to this message; however, the) s -5 184 M -( application may send EOF to whatever is at the other end of the) s -5 173 M -( channel. Note that the channel remains open after this message, and) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 6]) s -_R -S -PStoPSsaved restore -%%Page: (6,7) 4 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 7 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Connection Protocol Oct 2003) s -5 690 M -( more data may still be sent in the other direction. This message) s -5 679 M -( does not consume window space and can be sent even if no window space) s -5 668 M -( is available.) s -5 646 M -( When either party wishes to terminate the channel, it sends) s -5 635 M -( SSH_MSG_CHANNEL_CLOSE. Upon receiving this message, a party MUST) s -5 624 M -( send back a SSH_MSG_CHANNEL_CLOSE unless it has already sent this) s -5 613 M -( message for the channel. The channel is considered closed for a) s -5 602 M -( party when it has both sent and received SSH_MSG_CHANNEL_CLOSE, and) s -5 591 M -( the party may then reuse the channel number. A party MAY send) s -5 580 M -( SSH_MSG_CHANNEL_CLOSE without having sent or received) s -5 569 M -( SSH_MSG_CHANNEL_EOF.) s -5 547 M -( byte SSH_MSG_CHANNEL_CLOSE) s -5 536 M -( uint32 recipient_channel) s -5 514 M -( This message does not consume window space and can be sent even if no) s -5 503 M -( window space is available.) s -5 481 M -( It is recommended that any data sent before this message is delivered) s -5 470 M -( to the actual destination, if possible.) s -5 448 M -(5.4 Channel-Specific Requests) s -5 426 M -( Many channel types have extensions that are specific to that) s -5 415 M -( particular channel type. An example is requesting a pty \(pseudo) s -5 404 M -( terminal\) for an interactive session.) s -5 382 M -( All channel-specific requests use the following format.) s -5 360 M -( byte SSH_MSG_CHANNEL_REQUEST) s -5 349 M -( uint32 recipient channel) s -5 338 M -( string request type \(restricted to US-ASCII\)) s -5 327 M -( boolean want reply) s -5 316 M -( ... type-specific data) s -5 294 M -( If want reply is FALSE, no response will be sent to the request.) s -5 283 M -( Otherwise, the recipient responds with either SSH_MSG_CHANNEL_SUCCESS) s -5 272 M -( or SSH_MSG_CHANNEL_FAILURE, or request-specific continuation) s -5 261 M -( messages. If the request is not recognized or is not supported for) s -5 250 M -( the channel, SSH_MSG_CHANNEL_FAILURE is returned.) s -5 228 M -( This message does not consume window space and can be sent even if no) s -5 217 M -( window space is available. Request types are local to each channel) s -5 206 M -( type.) s -5 184 M -( The client is allowed to send further messages without waiting for) s -5 173 M -( the response to the request.) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 7]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 8 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Connection Protocol Oct 2003) s -5 690 M -( request type names follow the DNS extensibility naming convention) s -5 679 M -( outlined in [SSH-ARCH]) s -5 657 M -( byte SSH_MSG_CHANNEL_SUCCESS) s -5 646 M -( uint32 recipient_channel) s -5 613 M -( byte SSH_MSG_CHANNEL_FAILURE) s -5 602 M -( uint32 recipient_channel) s -5 580 M -( These messages do not consume window space and can be sent even if no) s -5 569 M -( window space is available.) s -5 547 M -(6. Interactive Sessions) s -5 525 M -( A session is a remote execution of a program. The program may be a) s -5 514 M -( shell, an application, a system command, or some built-in subsystem.) s -5 503 M -( It may or may not have a tty, and may or may not involve X11) s -5 492 M -( forwarding. Multiple sessions can be active simultaneously.) s -5 470 M -(6.1 Opening a Session) s -5 448 M -( A session is started by sending the following message.) s -5 426 M -( byte SSH_MSG_CHANNEL_OPEN) s -5 415 M -( string "session") s -5 404 M -( uint32 sender channel) s -5 393 M -( uint32 initial window size) s -5 382 M -( uint32 maximum packet size) s -5 360 M -( Client implementations SHOULD reject any session channel open) s -5 349 M -( requests to make it more difficult for a corrupt server to attack the) s -5 338 M -( client.) s -5 316 M -(6.2 Requesting a Pseudo-Terminal) s -5 294 M -( A pseudo-terminal can be allocated for the session by sending the) s -5 283 M -( following message.) s -5 261 M -( byte SSH_MSG_CHANNEL_REQUEST) s -5 250 M -( uint32 recipient_channel) s -5 239 M -( string "pty-req") s -5 228 M -( boolean want_reply) s -5 217 M -( string TERM environment variable value \(e.g., vt100\)) s -5 206 M -( uint32 terminal width, characters \(e.g., 80\)) s -5 195 M -( uint32 terminal height, rows \(e.g., 24\)) s -5 184 M -( uint32 terminal width, pixels \(e.g., 640\)) s -5 173 M -( uint32 terminal height, pixels \(e.g., 480\)) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 8]) s -_R -S -PStoPSsaved restore -%%Page: (8,9) 5 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 9 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Connection Protocol Oct 2003) s -5 690 M -( string encoded terminal modes) s -5 668 M -( The encoding of terminal modes is described in Section Encoding of) s -5 657 M -( Terminal Modes \(Section 8\). Zero dimension parameters MUST be) s -5 646 M -( ignored. The character/row dimensions override the pixel dimensions) s -5 635 M -( \(when nonzero\). Pixel dimensions refer to the drawable area of the) s -5 624 M -( window.) s -5 602 M -( The dimension parameters are only informational.) s -5 580 M -( The client SHOULD ignore pty requests.) s -5 558 M -(6.3 X11 Forwarding) s -5 536 M -(6.3.1 Requesting X11 Forwarding) s -5 514 M -( X11 forwarding may be requested for a session by sending) s -5 492 M -( byte SSH_MSG_CHANNEL_REQUEST) s -5 481 M -( uint32 recipient channel) s -5 470 M -( string "x11-req") s -5 459 M -( boolean want reply) s -5 448 M -( boolean single connection) s -5 437 M -( string x11 authentication protocol) s -5 426 M -( string x11 authentication cookie) s -5 415 M -( uint32 x11 screen number) s -5 393 M -( It is recommended that the authentication cookie that is sent be a) s -5 382 M -( fake, random cookie, and that the cookie is checked and replaced by) s -5 371 M -( the real cookie when a connection request is received.) s -5 349 M -( X11 connection forwarding should stop when the session channel is) s -5 338 M -( closed; however, already opened forwardings should not be) s -5 327 M -( automatically closed when the session channel is closed.) s -5 305 M -( If `single connection' is TRUE, only a single connection should be) s -5 294 M -( forwarded. No more connections will be forwarded after the first, or) s -5 283 M -( after the session channel has been closed.) s -5 261 M -( The "x11 authentication protocol" is the name of the X11) s -5 250 M -( authentication method used, e.g. "MIT-MAGIC-COOKIE-1".) s -5 228 M -( The x11 authentication cookie MUST be hexadecimal encoded.) s -5 206 M -( X Protocol is documented in [SCHEIFLER].) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 9]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 10 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Connection Protocol Oct 2003) s -5 690 M -(6.3.2 X11 Channels) s -5 668 M -( X11 channels are opened with a channel open request. The resulting) s -5 657 M -( channels are independent of the session, and closing the session) s -5 646 M -( channel does not close the forwarded X11 channels.) s -5 624 M -( byte SSH_MSG_CHANNEL_OPEN) s -5 613 M -( string "x11") s -5 602 M -( uint32 sender channel) s -5 591 M -( uint32 initial window size) s -5 580 M -( uint32 maximum packet size) s -5 569 M -( string originator address \(e.g. "192.168.7.38"\)) s -5 558 M -( uint32 originator port) s -5 536 M -( The recipient should respond with SSH_MSG_CHANNEL_OPEN_CONFIRMATION) s -5 525 M -( or SSH_MSG_CHANNEL_OPEN_FAILURE.) s -5 503 M -( Implementations MUST reject any X11 channel open requests if they) s -5 492 M -( have not requested X11 forwarding.) s -5 470 M -(6.4 Environment Variable Passing) s -5 448 M -( Environment variables may be passed to the shell/command to be) s -5 437 M -( started later. Uncontrolled setting of environment variables in a) s -5 426 M -( privileged process can be a security hazard. It is recommended that) s -5 415 M -( implementations either maintain a list of allowable variable names or) s -5 404 M -( only set environment variables after the server process has dropped) s -5 393 M -( sufficient privileges.) s -5 371 M -( byte SSH_MSG_CHANNEL_REQUEST) s -5 360 M -( uint32 recipient channel) s -5 349 M -( string "env") s -5 338 M -( boolean want reply) s -5 327 M -( string variable name) s -5 316 M -( string variable value) s -5 283 M -(6.5 Starting a Shell or a Command) s -5 261 M -( Once the session has been set up, a program is started at the remote) s -5 250 M -( end. The program can be a shell, an application program or a) s -5 239 M -( subsystem with a host-independent name. Only one of these requests) s -5 228 M -( can succeed per channel.) s -5 206 M -( byte SSH_MSG_CHANNEL_REQUEST) s -5 195 M -( uint32 recipient channel) s -5 184 M -( string "shell") s -5 173 M -( boolean want reply) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 10]) s -_R -S -PStoPSsaved restore -%%Page: (10,11) 6 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 11 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Connection Protocol Oct 2003) s -5 690 M -( This message will request the user's default shell \(typically defined) s -5 679 M -( in /etc/passwd in UNIX systems\) to be started at the other end.) s -5 657 M -( byte SSH_MSG_CHANNEL_REQUEST) s -5 646 M -( uint32 recipient channel) s -5 635 M -( string "exec") s -5 624 M -( boolean want reply) s -5 613 M -( string command) s -5 591 M -( This message will request the server to start the execution of the) s -5 580 M -( given command. The command string may contain a path. Normal) s -5 569 M -( precautions MUST be taken to prevent the execution of unauthorized) s -5 558 M -( commands.) s -5 536 M -( byte SSH_MSG_CHANNEL_REQUEST) s -5 525 M -( uint32 recipient channel) s -5 514 M -( string "subsystem") s -5 503 M -( boolean want reply) s -5 492 M -( string subsystem name) s -5 470 M -( This last form executes a predefined subsystem. It is expected that) s -5 459 M -( these will include a general file transfer mechanism, and possibly) s -5 448 M -( other features. Implementations may also allow configuring more such) s -5 437 M -( mechanisms. As the user's shell is usually used to execute the) s -5 426 M -( subsystem, it is advisable for the subsystem protocol to have a) s -5 415 M -( "magic cookie" at the beginning of the protocol transaction to) s -5 404 M -( distinguish it from arbitrary output generated by shell) s -5 393 M -( initialization scripts etc. This spurious output from the shell may) s -5 382 M -( be filtered out either at the server or at the client.) s -5 360 M -( The server SHOULD not halt the execution of the protocol stack when) s -5 349 M -( starting a shell or a program. All input and output from these SHOULD) s -5 338 M -( be redirected to the channel or to the encrypted tunnel.) s -5 316 M -( It is RECOMMENDED to request and check the reply for these messages.) s -5 305 M -( The client SHOULD ignore these messages.) s -5 283 M -( Subsystem names follow the DNS extensibility naming convention) s -5 272 M -( outlined in [SSH-ARCH].) s -5 250 M -(6.6 Session Data Transfer) s -5 228 M -( Data transfer for a session is done using SSH_MSG_CHANNEL_DATA and) s -5 217 M -( SSH_MSG_CHANNEL_EXTENDED_DATA packets and the window mechanism. The) s -5 206 M -( extended data type SSH_EXTENDED_DATA_STDERR has been defined for) s -5 195 M -( stderr data.) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 11]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 12 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Connection Protocol Oct 2003) s -5 690 M -(6.7 Window Dimension Change Message) s -5 668 M -( When the window \(terminal\) size changes on the client side, it MAY) s -5 657 M -( send a message to the other side to inform it of the new dimensions.) s -5 635 M -( byte SSH_MSG_CHANNEL_REQUEST) s -5 624 M -( uint32 recipient_channel) s -5 613 M -( string "window-change") s -5 602 M -( boolean FALSE) s -5 591 M -( uint32 terminal width, columns) s -5 580 M -( uint32 terminal height, rows) s -5 569 M -( uint32 terminal width, pixels) s -5 558 M -( uint32 terminal height, pixels) s -5 536 M -( No response SHOULD be sent to this message.) s -5 514 M -(6.8 Local Flow Control) s -5 492 M -( On many systems, it is possible to determine if a pseudo-terminal is) s -5 481 M -( using control-S/control-Q flow control. When flow control is) s -5 470 M -( allowed, it is often desirable to do the flow control at the client) s -5 459 M -( end to speed up responses to user requests. This is facilitated by) s -5 448 M -( the following notification. Initially, the server is responsible for) s -5 437 M -( flow control. \(Here, again, client means the side originating the) s -5 426 M -( session, and server means the other side.\)) s -5 404 M -( The message below is used by the server to inform the client when it) s -5 393 M -( can or cannot perform flow control \(control-S/control-Q processing\).) s -5 382 M -( If `client can do' is TRUE, the client is allowed to do flow control) s -5 371 M -( using control-S and control-Q. The client MAY ignore this message.) s -5 349 M -( byte SSH_MSG_CHANNEL_REQUEST) s -5 338 M -( uint32 recipient channel) s -5 327 M -( string "xon-xoff") s -5 316 M -( boolean FALSE) s -5 305 M -( boolean client can do) s -5 283 M -( No response is sent to this message.) s -5 261 M -(6.9 Signals) s -5 239 M -( A signal can be delivered to the remote process/service using the) s -5 228 M -( following message. Some systems may not implement signals, in which) s -5 217 M -( case they SHOULD ignore this message.) s -5 195 M -( byte SSH_MSG_CHANNEL_REQUEST) s -5 184 M -( uint32 recipient channel) s -5 173 M -( string "signal") s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 12]) s -_R -S -PStoPSsaved restore -%%Page: (12,13) 7 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 13 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Connection Protocol Oct 2003) s -5 690 M -( boolean FALSE) s -5 679 M -( string signal name without the "SIG" prefix.) s -5 657 M -( Signal names will be encoded as discussed in the "exit-signal") s -5 646 M -( SSH_MSG_CHANNEL_REQUEST.) s -5 624 M -(6.10 Returning Exit Status) s -5 602 M -( When the command running at the other end terminates, the following) s -5 591 M -( message can be sent to return the exit status of the command.) s -5 580 M -( Returning the status is RECOMMENDED. No acknowledgment is sent for) s -5 569 M -( this message. The channel needs to be closed with) s -5 558 M -( SSH_MSG_CHANNEL_CLOSE after this message.) s -5 536 M -( The client MAY ignore these messages.) s -5 514 M -( byte SSH_MSG_CHANNEL_REQUEST) s -5 503 M -( uint32 recipient_channel) s -5 492 M -( string "exit-status") s -5 481 M -( boolean FALSE) s -5 470 M -( uint32 exit_status) s -5 448 M -( The remote command may also terminate violently due to a signal.) s -5 437 M -( Such a condition can be indicated by the following message. A zero) s -5 426 M -( exit_status usually means that the command terminated successfully.) s -5 404 M -( byte SSH_MSG_CHANNEL_REQUEST) s -5 393 M -( uint32 recipient channel) s -5 382 M -( string "exit-signal") s -5 371 M -( boolean FALSE) s -5 360 M -( string signal name without the "SIG" prefix.) s -5 349 M -( boolean core dumped) s -5 338 M -( string error message \(ISO-10646 UTF-8\)) s -5 327 M -( string language tag \(as defined in [RFC3066]\)) s -5 305 M -( The signal name is one of the following \(these are from [POSIX]\)) s -5 283 M -( ABRT) s -5 272 M -( ALRM) s -5 261 M -( FPE) s -5 250 M -( HUP) s -5 239 M -( ILL) s -5 228 M -( INT) s -5 217 M -( KILL) s -5 206 M -( PIPE) s -5 195 M -( QUIT) s -5 184 M -( SEGV) s -5 173 M -( TERM) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 13]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 14 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Connection Protocol Oct 2003) s -5 690 M -( USR1) s -5 679 M -( USR2) s -5 657 M -( Additional signal names MAY be sent in the format "sig-name@xyz",) s -5 646 M -( where `sig-name' and `xyz' may be anything a particular implementor) s -5 635 M -( wants \(except the `@' sign\). However, it is suggested that if a) s -5 624 M -( `configure' script is used, the non-standard signal names it finds be) s -5 613 M -( encoded as "[email protected]", where `SIG' is the signal name) s -5 602 M -( without the "SIG" prefix, and `xyz' be the host type, as determined) s -5 591 M -( by `config.guess'.) s -5 569 M -( The `error message' contains an additional explanation of the error) s -5 558 M -( message. The message may consist of multiple lines. The client) s -5 547 M -( software MAY display this message to the user. If this is done, the) s -5 536 M -( client software should take the precautions discussed in [SSH-ARCH].) s -5 514 M -(7. TCP/IP Port Forwarding) s -5 492 M -(7.1 Requesting Port Forwarding) s -5 470 M -( A party need not explicitly request forwardings from its own end to) s -5 459 M -( the other direction. However, if it wishes that connections to a) s -5 448 M -( port on the other side be forwarded to the local side, it must) s -5 437 M -( explicitly request this.) s -5 404 M -( byte SSH_MSG_GLOBAL_REQUEST) s -5 393 M -( string "tcpip-forward") s -5 382 M -( boolean want reply) s -5 371 M -( string address to bind \(e.g. "0.0.0.0"\)) s -5 360 M -( uint32 port number to bind) s -5 338 M -( `Address to bind' and `port number to bind' specify the IP address) s -5 327 M -( and port to which the socket to be listened is bound. The address) s -5 316 M -( should be "0.0.0.0" if connections are allowed from anywhere. \(Note) s -5 305 M -( that the client can still filter connections based on information) s -5 294 M -( passed in the open request.\)) s -5 272 M -( Implementations should only allow forwarding privileged ports if the) s -5 261 M -( user has been authenticated as a privileged user.) s -5 239 M -( Client implementations SHOULD reject these messages; they are) s -5 228 M -( normally only sent by the client.) s -5 195 M -( If a client passes 0 as port number to bind and has want reply TRUE) s -5 184 M -( then the server allocates the next available unprivileged port number) s -5 173 M -( and replies with the following message, otherwise there is no) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 14]) s -_R -S -PStoPSsaved restore -%%Page: (14,15) 8 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 15 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Connection Protocol Oct 2003) s -5 690 M -( response specific data.) s -5 657 M -( byte SSH_MSG_GLOBAL_REQUEST_SUCCESS) s -5 646 M -( uint32 port that was bound on the server) s -5 624 M -( A port forwarding can be cancelled with the following message. Note) s -5 613 M -( that channel open requests may be received until a reply to this) s -5 602 M -( message is received.) s -5 580 M -( byte SSH_MSG_GLOBAL_REQUEST) s -5 569 M -( string "cancel-tcpip-forward") s -5 558 M -( boolean want reply) s -5 547 M -( string address_to_bind \(e.g. "127.0.0.1"\)) s -5 536 M -( uint32 port number to bind) s -5 514 M -( Client implementations SHOULD reject these messages; they are) s -5 503 M -( normally only sent by the client.) s -5 481 M -(7.2 TCP/IP Forwarding Channels) s -5 459 M -( When a connection comes to a port for which remote forwarding has) s -5 448 M -( been requested, a channel is opened to forward the port to the other) s -5 437 M -( side.) s -5 415 M -( byte SSH_MSG_CHANNEL_OPEN) s -5 404 M -( string "forwarded-tcpip") s -5 393 M -( uint32 sender channel) s -5 382 M -( uint32 initial window size) s -5 371 M -( uint32 maximum packet size) s -5 360 M -( string address that was connected) s -5 349 M -( uint32 port that was connected) s -5 338 M -( string originator IP address) s -5 327 M -( uint32 originator port) s -5 305 M -( Implementations MUST reject these messages unless they have) s -5 294 M -( previously requested a remote TCP/IP port forwarding with the given) s -5 283 M -( port number.) s -5 261 M -( When a connection comes to a locally forwarded TCP/IP port, the) s -5 250 M -( following packet is sent to the other side. Note that these messages) s -5 239 M -( MAY be sent also for ports for which no forwarding has been) s -5 228 M -( explicitly requested. The receiving side must decide whether to) s -5 217 M -( allow the forwarding.) s -5 195 M -( byte SSH_MSG_CHANNEL_OPEN) s -5 184 M -( string "direct-tcpip") s -5 173 M -( uint32 sender channel) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 15]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 16 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Connection Protocol Oct 2003) s -5 690 M -( uint32 initial window size) s -5 679 M -( uint32 maximum packet size) s -5 668 M -( string host to connect) s -5 657 M -( uint32 port to connect) s -5 646 M -( string originator IP address) s -5 635 M -( uint32 originator port) s -5 613 M -( `Host to connect' and `port to connect' specify the TCP/IP host and) s -5 602 M -( port where the recipient should connect the channel. `Host to) s -5 591 M -( connect' may be either a domain name or a numeric IP address.) s -5 569 M -( `Originator IP address' is the numeric IP address of the machine) s -5 558 M -( where the connection request comes from, and `originator port' is the) s -5 547 M -( port on the originator host from where the connection came from.) s -5 525 M -( Forwarded TCP/IP channels are independent of any sessions, and) s -5 514 M -( closing a session channel does not in any way imply that forwarded) s -5 503 M -( connections should be closed.) s -5 481 M -( Client implementations SHOULD reject direct TCP/IP open requests for) s -5 470 M -( security reasons.) s -5 448 M -(8. Encoding of Terminal Modes) s -5 426 M -( Terminal modes \(as passed in a pty request\) are encoded into a byte) s -5 415 M -( stream. It is intended that the coding be portable across different) s -5 404 M -( environments.) s -5 382 M -( The tty mode description is a stream of bytes. The stream consists) s -5 371 M -( of opcode-argument pairs. It is terminated by opcode TTY_OP_END \(0\).) s -5 360 M -( Opcodes 1 to 159 have a single uint32 argument. Opcodes 160 to 255) s -5 349 M -( are not yet defined, and cause parsing to stop \(they should only be) s -5 338 M -( used after any other data\).) s -5 316 M -( The client SHOULD put in the stream any modes it knows about, and the) s -5 305 M -( server MAY ignore any modes it does not know about. This allows some) s -5 294 M -( degree of machine-independence, at least between systems that use a) s -5 283 M -( POSIX-like tty interface. The protocol can support other systems as) s -5 272 M -( well, but the client may need to fill reasonable values for a number) s -5 261 M -( of parameters so the server pty gets set to a reasonable mode \(the) s -5 250 M -( server leaves all unspecified mode bits in their default values, and) s -5 239 M -( only some combinations make sense\).) s -5 217 M -( The following opcodes have been defined. The naming of opcodes) s -5 206 M -( mostly follows the POSIX terminal mode flags.) s -5 184 M -( 0 TTY_OP_END Indicates end of options.) s -5 173 M -( 1 VINTR Interrupt character; 255 if none. Similarly for the) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 16]) s -_R -S -PStoPSsaved restore -%%Page: (16,17) 9 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 17 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Connection Protocol Oct 2003) s -5 690 M -( other characters. Not all of these characters are) s -5 679 M -( supported on all systems.) s -5 668 M -( 2 VQUIT The quit character \(sends SIGQUIT signal on POSIX) s -5 657 M -( systems\).) s -5 646 M -( 3 VERASE Erase the character to left of the cursor.) s -5 635 M -( 4 VKILL Kill the current input line.) s -5 624 M -( 5 VEOF End-of-file character \(sends EOF from the terminal\).) s -5 613 M -( 6 VEOL End-of-line character in addition to carriage return) s -5 602 M -( and/or linefeed.) s -5 591 M -( 7 VEOL2 Additional end-of-line character.) s -5 580 M -( 8 VSTART Continues paused output \(normally control-Q\).) s -5 569 M -( 9 VSTOP Pauses output \(normally control-S\).) s -5 558 M -( 10 VSUSP Suspends the current program.) s -5 547 M -( 11 VDSUSP Another suspend character.) s -5 536 M -( 12 VREPRINT Reprints the current input line.) s -5 525 M -( 13 VWERASE Erases a word left of cursor.) s -5 514 M -( 14 VLNEXT Enter the next character typed literally, even if it) s -5 503 M -( is a special character) s -5 492 M -( 15 VFLUSH Character to flush output.) s -5 481 M -( 16 VSWTCH Switch to a different shell layer.) s -5 470 M -( 17 VSTATUS Prints system status line \(load, command, pid etc\).) s -5 459 M -( 18 VDISCARD Toggles the flushing of terminal output.) s -5 448 M -( 30 IGNPAR The ignore parity flag. The parameter SHOULD be 0 if) s -5 437 M -( this flag is FALSE set, and 1 if it is TRUE.) s -5 426 M -( 31 PARMRK Mark parity and framing errors.) s -5 415 M -( 32 INPCK Enable checking of parity errors.) s -5 404 M -( 33 ISTRIP Strip 8th bit off characters.) s -5 393 M -( 34 INLCR Map NL into CR on input.) s -5 382 M -( 35 IGNCR Ignore CR on input.) s -5 371 M -( 36 ICRNL Map CR to NL on input.) s -5 360 M -( 37 IUCLC Translate uppercase characters to lowercase.) s -5 349 M -( 38 IXON Enable output flow control.) s -5 338 M -( 39 IXANY Any char will restart after stop.) s -5 327 M -( 40 IXOFF Enable input flow control.) s -5 316 M -( 41 IMAXBEL Ring bell on input queue full.) s -5 305 M -( 50 ISIG Enable signals INTR, QUIT, [D]SUSP.) s -5 294 M -( 51 ICANON Canonicalize input lines.) s -5 283 M -( 52 XCASE Enable input and output of uppercase characters by) s -5 272 M -( preceding their lowercase equivalents with `\\'.) s -5 261 M -( 53 ECHO Enable echoing.) s -5 250 M -( 54 ECHOE Visually erase chars.) s -5 239 M -( 55 ECHOK Kill character discards current line.) s -5 228 M -( 56 ECHONL Echo NL even if ECHO is off.) s -5 217 M -( 57 NOFLSH Don't flush after interrupt.) s -5 206 M -( 58 TOSTOP Stop background jobs from output.) s -5 195 M -( 59 IEXTEN Enable extensions.) s -5 184 M -( 60 ECHOCTL Echo control characters as ^\(Char\).) s -5 173 M -( 61 ECHOKE Visual erase for line kill.) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 17]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 18 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Connection Protocol Oct 2003) s -5 690 M -( 62 PENDIN Retype pending input.) s -5 679 M -( 70 OPOST Enable output processing.) s -5 668 M -( 71 OLCUC Convert lowercase to uppercase.) s -5 657 M -( 72 ONLCR Map NL to CR-NL.) s -5 646 M -( 73 OCRNL Translate carriage return to newline \(output\).) s -5 635 M -( 74 ONOCR Translate newline to carriage return-newline) s -5 624 M -( \(output\).) s -5 613 M -( 75 ONLRET Newline performs a carriage return \(output\).) s -5 602 M -( 90 CS7 7 bit mode.) s -5 591 M -( 91 CS8 8 bit mode.) s -5 580 M -( 92 PARENB Parity enable.) s -5 569 M -( 93 PARODD Odd parity, else even.) s -5 547 M -( 128 TTY_OP_ISPEED Specifies the input baud rate in bits per second.) s -5 536 M -( 129 TTY_OP_OSPEED Specifies the output baud rate in bits per second.) s -5 503 M -(9. Summary of Message Numbers) s -5 481 M -( #define SSH_MSG_GLOBAL_REQUEST 80) s -5 470 M -( #define SSH_MSG_REQUEST_SUCCESS 81) s -5 459 M -( #define SSH_MSG_REQUEST_FAILURE 82) s -5 448 M -( #define SSH_MSG_CHANNEL_OPEN 90) s -5 437 M -( #define SSH_MSG_CHANNEL_OPEN_CONFIRMATION 91) s -5 426 M -( #define SSH_MSG_CHANNEL_OPEN_FAILURE 92) s -5 415 M -( #define SSH_MSG_CHANNEL_WINDOW_ADJUST 93) s -5 404 M -( #define SSH_MSG_CHANNEL_DATA 94) s -5 393 M -( #define SSH_MSG_CHANNEL_EXTENDED_DATA 95) s -5 382 M -( #define SSH_MSG_CHANNEL_EOF 96) s -5 371 M -( #define SSH_MSG_CHANNEL_CLOSE 97) s -5 360 M -( #define SSH_MSG_CHANNEL_REQUEST 98) s -5 349 M -( #define SSH_MSG_CHANNEL_SUCCESS 99) s -5 338 M -( #define SSH_MSG_CHANNEL_FAILURE 100) s -5 305 M -(10. Security Considerations) s -5 283 M -( This protocol is assumed to run on top of a secure, authenticated) s -5 272 M -( transport. User authentication and protection against network-level) s -5 261 M -( attacks are assumed to be provided by the underlying protocols.) s -5 239 M -( It is RECOMMENDED that implementations disable all the potentially) s -5 228 M -( dangerous features \(e.g. agent forwarding, X11 forwarding, and TCP/IP) s -5 217 M -( forwarding\) if the host key has changed.) s -5 195 M -( Full security considerations for this protocol are provided in) s -5 184 M -( Section 8 of [SSH-ARCH]) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 18]) s -_R -S -PStoPSsaved restore -%%Page: (18,19) 10 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 19 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Connection Protocol Oct 2003) s -5 690 M -(11. iana cONSiderations) s -5 668 M -( This document is part of a set, the IANA considerations for the SSH) s -5 657 M -( protocol as defined in [SSH-ARCH], [SSH-TRANS], [SSH-USERAUTH],) s -5 646 M -( [SSH-CONNECT] are detailed in [SSH-NUMBERS].) s -5 624 M -(12. Intellectual Property) s -5 602 M -( The IETF takes no position regarding the validity or scope of any) s -5 591 M -( intellectual property or other rights that might be claimed to) s -5 580 M -( pertain to the implementation or use of the technology described in) s -5 569 M -( this document or the extent to which any license under such rights) s -5 558 M -( might or might not be available; neither does it represent that it) s -5 547 M -( has made any effort to identify any such rights. Information on the) s -5 536 M -( IETF's procedures with respect to rights in standards-track and) s -5 525 M -( standards-related documentation can be found in BCP-11. Copies of) s -5 514 M -( claims of rights made available for publication and any assurances of) s -5 503 M -( licenses to be made available, or the result of an attempt made to) s -5 492 M -( obtain a general license or permission for the use of such) s -5 481 M -( proprietary rights by implementers or users of this specification can) s -5 470 M -( be obtained from the IETF Secretariat.) s -5 448 M -( The IETF has been notified of intellectual property rights claimed in) s -5 437 M -( regard to some or all of the specification contained in this) s -5 426 M -( document. For more information consult the online list of claimed) s -5 415 M -( rights.) s -5 393 M -(Normative References) s -5 371 M -( [SSH-ARCH]) s -5 360 M -( Ylonen, T., "SSH Protocol Architecture", I-D) s -5 349 M -( draft-ietf-architecture-15.txt, Oct 2003.) s -5 327 M -( [SSH-TRANS]) s -5 316 M -( Ylonen, T., "SSH Transport Layer Protocol", I-D) s -5 305 M -( draft-ietf-transport-17.txt, Oct 2003.) s -5 283 M -( [SSH-USERAUTH]) s -5 272 M -( Ylonen, T., "SSH Authentication Protocol", I-D) s -5 261 M -( draft-ietf-userauth-18.txt, Oct 2003.) s -5 239 M -( [SSH-CONNECT]) s -5 228 M -( Ylonen, T., "SSH Connection Protocol", I-D) s -5 217 M -( draft-ietf-connect-18.txt, Oct 2003.) s -5 195 M -( [SSH-NUMBERS]) s -5 184 M -( Lehtinen, S. and D. Moffat, "SSH Protocol Assigned) s -5 173 M -( Numbers", I-D draft-ietf-secsh-assignednumbers-05.txt, Oct) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 19]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 20 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Connection Protocol Oct 2003) s -5 690 M -( 2003.) s -5 668 M -( [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate) s -5 657 M -( Requirement Levels", BCP 14, RFC 2119, March 1997.) s -5 635 M -(Informative References) s -5 613 M -( [RFC3066] Alvestrand, H., "Tags for the Identification of) s -5 602 M -( Languages", BCP 47, RFC 3066, January 2001.) s -5 580 M -( [RFC1884] Hinden, R. and S. Deering, "IP Version 6 Addressing) s -5 569 M -( Architecture", RFC 1884, December 1995.) s -5 547 M -( [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO) s -5 536 M -( 10646", RFC 2279, January 1998.) s -5 514 M -( [SCHEIFLER]) s -5 503 M -( Scheifler, R., "X Window System : The Complete Reference) s -5 492 M -( to Xlib, X Protocol, Icccm, Xlfd, 3rd edition.", Digital) s -5 481 M -( Press ISBN 1555580882, Feburary 1992.) s -5 459 M -( [POSIX] ISO/IEC, 9945-1., "Information technology -- Portable) s -5 448 M -( Operating System Interface \(POSIX\)-Part 1: System) s -5 437 M -( Application Program Interface \(API\) C Language", ANSI/IEE) s -5 426 M -( Std 1003.1, July 1996.) s -5 393 M -(Authors' Addresses) s -5 371 M -( Tatu Ylonen) s -5 360 M -( SSH Communications Security Corp) s -5 349 M -( Fredrikinkatu 42) s -5 338 M -( HELSINKI FIN-00100) s -5 327 M -( Finland) s -5 305 M -( EMail: [email protected]) s -5 272 M -( Darren J. Moffat \(editor\)) s -5 261 M -( Sun Microsystems, Inc) s -5 250 M -( 17 Network Circle) s -5 239 M -( Menlo Park CA 94025) s -5 228 M -( USA) s -5 206 M -( EMail: [email protected]) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 20]) s -_R -S -PStoPSsaved restore -%%Page: (20,21) 11 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 21 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Connection Protocol Oct 2003) s -5 690 M -(Intellectual Property Statement) s -5 668 M -( The IETF takes no position regarding the validity or scope of any) s -5 657 M -( intellectual property or other rights that might be claimed to) s -5 646 M -( pertain to the implementation or use of the technology described in) s -5 635 M -( this document or the extent to which any license under such rights) s -5 624 M -( might or might not be available; neither does it represent that it) s -5 613 M -( has made any effort to identify any such rights. Information on the) s -5 602 M -( IETF's procedures with respect to rights in standards-track and) s -5 591 M -( standards-related documentation can be found in BCP-11. Copies of) s -5 580 M -( claims of rights made available for publication and any assurances of) s -5 569 M -( licenses to be made available, or the result of an attempt made to) s -5 558 M -( obtain a general license or permission for the use of such) s -5 547 M -( proprietary rights by implementors or users of this specification can) s -5 536 M -( be obtained from the IETF Secretariat.) s -5 514 M -( The IETF invites any interested party to bring to its attention any) s -5 503 M -( copyrights, patents or patent applications, or other proprietary) s -5 492 M -( rights which may cover technology that may be required to practice) s -5 481 M -( this standard. Please address the information to the IETF Executive) s -5 470 M -( Director.) s -5 448 M -( The IETF has been notified of intellectual property rights claimed in) s -5 437 M -( regard to some or all of the specification contained in this) s -5 426 M -( document. For more information consult the online list of claimed) s -5 415 M -( rights.) s -5 382 M -(Full Copyright Statement) s -5 360 M -( Copyright \(C\) The Internet Society \(2003\). All Rights Reserved.) s -5 338 M -( This document and translations of it may be copied and furnished to) s -5 327 M -( others, and derivative works that comment on or otherwise explain it) s -5 316 M -( or assist in its implementation may be prepared, copied, published) s -5 305 M -( and distributed, in whole or in part, without restriction of any) s -5 294 M -( kind, provided that the above copyright notice and this paragraph are) s -5 283 M -( included on all such copies and derivative works. However, this) s -5 272 M -( document itself may not be modified in any way, such as by removing) s -5 261 M -( the copyright notice or references to the Internet Society or other) s -5 250 M -( Internet organizations, except as needed for the purpose of) s -5 239 M -( developing Internet standards in which case the procedures for) s -5 228 M -( copyrights defined in the Internet Standards process must be) s -5 217 M -( followed, or as required to translate it into languages other than) s -5 206 M -( English.) s -5 184 M -( The limited permissions granted above are perpetual and will not be) s -5 173 M -( revoked by the Internet Society or its successors or assignees.) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 21]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 22 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Connection Protocol Oct 2003) s -5 690 M -( This document and the information contained herein is provided on an) s -5 679 M -( "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING) s -5 668 M -( TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING) s -5 657 M -( BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION) s -5 646 M -( HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF) s -5 635 M -( MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.) s -5 602 M -(Acknowledgment) s -5 580 M -( Funding for the RFC Editor function is currently provided by the) s -5 569 M -( Internet Society.) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 22]) s -_R -S -PStoPSsaved restore -%%Trailer -%%Pages: 22 -%%DocumentNeededResources: font Courier-Bold Courier -%%EOF diff --git a/lib/ssh/doc/standard/draft-ietf-secsh-connect-18.txt b/lib/ssh/doc/standard/draft-ietf-secsh-connect-18.txt deleted file mode 100644 index 1cb8ad6409..0000000000 --- a/lib/ssh/doc/standard/draft-ietf-secsh-connect-18.txt +++ /dev/null @@ -1,1232 +0,0 @@ - - - -Network Working Group T. Ylonen -Internet-Draft SSH Communications Security Corp -Expires: March 31, 2004 D. Moffat, Editor, Ed. - Sun Microsystems, Inc - Oct 2003 - - - SSH Connection Protocol - draft-ietf-secsh-connect-18.txt - -Status of this Memo - - This document is an Internet-Draft and is in full conformance with - all provisions of Section 10 of RFC2026. - - Internet-Drafts are working documents of the Internet Engineering - Task Force (IETF), its areas, and its working groups. Note that other - groups may also distribute working documents as Internet-Drafts. - - Internet-Drafts are draft documents valid for a maximum of six months - and may be updated, replaced, or obsoleted by other documents at any - time. It is inappropriate to use Internet-Drafts as reference - material or to cite them other than as "work in progress." - - The list of current Internet-Drafts can be accessed at http:// - www.ietf.org/ietf/1id-abstracts.txt. - - The list of Internet-Draft Shadow Directories can be accessed at - http://www.ietf.org/shadow.html. - - This Internet-Draft will expire on March 31, 2004. - -Copyright Notice - - Copyright (C) The Internet Society (2003). All Rights Reserved. - -Abstract - - SSH is a protocol for secure remote login and other secure network - services over an insecure network. - - This document describes the SSH Connection Protocol. It provides - interactive login sessions, remote execution of commands, forwarded - TCP/IP connections, and forwarded X11 connections. All of these - channels are multiplexed into a single encrypted tunnel. - - The SSH Connection Protocol has been designed to run on top of the - SSH transport layer and user authentication protocols. - - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 1] - -Internet-Draft SSH Connection Protocol Oct 2003 - - -Table of Contents - - 1. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 3 - 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 - 3. Conventions Used in This Document . . . . . . . . . . . . . 3 - 4. Global Requests . . . . . . . . . . . . . . . . . . . . . . 3 - 5. Channel Mechanism . . . . . . . . . . . . . . . . . . . . . 4 - 5.1 Opening a Channel . . . . . . . . . . . . . . . . . . . . . 4 - 5.2 Data Transfer . . . . . . . . . . . . . . . . . . . . . . . 5 - 5.3 Closing a Channel . . . . . . . . . . . . . . . . . . . . . 6 - 5.4 Channel-Specific Requests . . . . . . . . . . . . . . . . . 7 - 6. Interactive Sessions . . . . . . . . . . . . . . . . . . . . 8 - 6.1 Opening a Session . . . . . . . . . . . . . . . . . . . . . 8 - 6.2 Requesting a Pseudo-Terminal . . . . . . . . . . . . . . . . 8 - 6.3 X11 Forwarding . . . . . . . . . . . . . . . . . . . . . . . 9 - 6.3.1 Requesting X11 Forwarding . . . . . . . . . . . . . . . . . 9 - 6.3.2 X11 Channels . . . . . . . . . . . . . . . . . . . . . . . . 10 - 6.4 Environment Variable Passing . . . . . . . . . . . . . . . . 10 - 6.5 Starting a Shell or a Command . . . . . . . . . . . . . . . 10 - 6.6 Session Data Transfer . . . . . . . . . . . . . . . . . . . 11 - 6.7 Window Dimension Change Message . . . . . . . . . . . . . . 12 - 6.8 Local Flow Control . . . . . . . . . . . . . . . . . . . . . 12 - 6.9 Signals . . . . . . . . . . . . . . . . . . . . . . . . . . 12 - 6.10 Returning Exit Status . . . . . . . . . . . . . . . . . . . 13 - 7. TCP/IP Port Forwarding . . . . . . . . . . . . . . . . . . . 14 - 7.1 Requesting Port Forwarding . . . . . . . . . . . . . . . . . 14 - 7.2 TCP/IP Forwarding Channels . . . . . . . . . . . . . . . . . 15 - 8. Encoding of Terminal Modes . . . . . . . . . . . . . . . . . 16 - 9. Summary of Message Numbers . . . . . . . . . . . . . . . . . 18 - 10. Security Considerations . . . . . . . . . . . . . . . . . . 18 - 11. iana cONSiderations . . . . . . . . . . . . . . . . . . . . 19 - 12. Intellectual Property . . . . . . . . . . . . . . . . . . . 19 - Normative References . . . . . . . . . . . . . . . . . . . . 19 - Informative References . . . . . . . . . . . . . . . . . . . 20 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 20 - Intellectual Property and Copyright Statements . . . . . . . 21 - - - - - - - - - - - - - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 2] - -Internet-Draft SSH Connection Protocol Oct 2003 - - -1. Contributors - - The major original contributors of this document were: Tatu Ylonen, - Tero Kivinen, Timo J. Rinne, Sami Lehtinen (all of SSH Communications - Security Corp), and Markku-Juhani O. Saarinen (University of - Jyvaskyla) - - The document editor is: [email protected]. Comments on this - internet draft should be sent to the IETF SECSH working group, - details at: http://ietf.org/html.charters/secsh-charter.html - -2. Introduction - - The SSH Connection Protocol has been designed to run on top of the - SSH transport layer and user authentication protocols. It provides - interactive login sessions, remote execution of commands, forwarded - TCP/IP connections, and forwarded X11 connections. The service name - for this protocol is "ssh-connection". - - This document should be read only after reading the SSH architecture - document [SSH-ARCH]. This document freely uses terminology and - notation from the architecture document without reference or further - explanation. - -3. Conventions Used in This Document - - The keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", - and "MAY" that appear in this document are to be interpreted as - described in [RFC2119]. - - The used data types and terminology are specified in the architecture - document [SSH-ARCH]. - - The architecture document also discusses the algorithm naming - conventions that MUST be used with the SSH protocols. - -4. Global Requests - - There are several kinds of requests that affect the state of the - remote end "globally", independent of any channels. An example is a - request to start TCP/IP forwarding for a specific port. All such - requests use the following format. - - byte SSH_MSG_GLOBAL_REQUEST - string request name (restricted to US-ASCII) - boolean want reply - ... request-specific data follows - - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 3] - -Internet-Draft SSH Connection Protocol Oct 2003 - - - Request names follow the DNS extensibility naming convention outlined - in [SSH-ARCH]. - - The recipient will respond to this message with - SSH_MSG_REQUEST_SUCCESS or SSH_MSG_REQUEST_FAILURE if `want reply' is - TRUE. - - byte SSH_MSG_REQUEST_SUCCESS - ..... response specific data - - Usually the response specific data is non-existent. - - If the recipient does not recognize or support the request, it simply - responds with SSH_MSG_REQUEST_FAILURE. - - byte SSH_MSG_REQUEST_FAILURE - - -5. Channel Mechanism - - All terminal sessions, forwarded connections, etc. are channels. - Either side may open a channel. Multiple channels are multiplexed - into a single connection. - - Channels are identified by numbers at each end. The number referring - to a channel may be different on each side. Requests to open a - channel contain the sender's channel number. Any other - channel-related messages contain the recipient's channel number for - the channel. - - Channels are flow-controlled. No data may be sent to a channel until - a message is received to indicate that window space is available. - -5.1 Opening a Channel - - When either side wishes to open a new channel, it allocates a local - number for the channel. It then sends the following message to the - other side, and includes the local channel number and initial window - size in the message. - - byte SSH_MSG_CHANNEL_OPEN - string channel type (restricted to US-ASCII) - uint32 sender channel - uint32 initial window size - uint32 maximum packet size - ... channel type specific data follows - - The channel type is a name as described in the SSH architecture - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 4] - -Internet-Draft SSH Connection Protocol Oct 2003 - - - document, with similar extension mechanisms. `sender channel' is a - local identifier for the channel used by the sender of this message. - `initial window size' specifies how many bytes of channel data can be - sent to the sender of this message without adjusting the window. - `Maximum packet size' specifies the maximum size of an individual - data packet that can be sent to the sender (for example, one might - want to use smaller packets for interactive connections to get better - interactive response on slow links). - - The remote side then decides whether it can open the channel, and - responds with either - - byte SSH_MSG_CHANNEL_OPEN_CONFIRMATION - uint32 recipient channel - uint32 sender channel - uint32 initial window size - uint32 maximum packet size - ... channel type specific data follows - - where `recipient channel' is the channel number given in the original - open request, and `sender channel' is the channel number allocated by - the other side, or - - byte SSH_MSG_CHANNEL_OPEN_FAILURE - uint32 recipient channel - uint32 reason code - string additional textual information (ISO-10646 UTF-8 [RFC2279]) - string language tag (as defined in [RFC3066]) - - If the recipient of the SSH_MSG_CHANNEL_OPEN message does not support - the specified channel type, it simply responds with - SSH_MSG_CHANNEL_OPEN_FAILURE. The client MAY show the additional - information to the user. If this is done, the client software should - take the precautions discussed in [SSH-ARCH]. - - The following reason codes are defined: - - #define SSH_OPEN_ADMINISTRATIVELY_PROHIBITED 1 - #define SSH_OPEN_CONNECT_FAILED 2 - #define SSH_OPEN_UNKNOWN_CHANNEL_TYPE 3 - #define SSH_OPEN_RESOURCE_SHORTAGE 4 - - -5.2 Data Transfer - - The window size specifies how many bytes the other party can send - before it must wait for the window to be adjusted. Both parties use - the following message to adjust the window. - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 5] - -Internet-Draft SSH Connection Protocol Oct 2003 - - - byte SSH_MSG_CHANNEL_WINDOW_ADJUST - uint32 recipient channel - uint32 bytes to add - - After receiving this message, the recipient MAY send the given number - of bytes more than it was previously allowed to send; the window size - is incremented. - - Data transfer is done with messages of the following type. - - byte SSH_MSG_CHANNEL_DATA - uint32 recipient channel - string data - - The maximum amount of data allowed is the current window size. The - window size is decremented by the amount of data sent. Both parties - MAY ignore all extra data sent after the allowed window is empty. - - Additionally, some channels can transfer several types of data. An - example of this is stderr data from interactive sessions. Such data - can be passed with SSH_MSG_CHANNEL_EXTENDED_DATA messages, where a - separate integer specifies the type of the data. The available types - and their interpretation depend on the type of the channel. - - byte SSH_MSG_CHANNEL_EXTENDED_DATA - uint32 recipient_channel - uint32 data_type_code - string data - - Data sent with these messages consumes the same window as ordinary - data. - - Currently, only the following type is defined. - - #define SSH_EXTENDED_DATA_STDERR 1 - - -5.3 Closing a Channel - - When a party will no longer send more data to a channel, it SHOULD - send SSH_MSG_CHANNEL_EOF. - - byte SSH_MSG_CHANNEL_EOF - uint32 recipient_channel - - No explicit response is sent to this message; however, the - application may send EOF to whatever is at the other end of the - channel. Note that the channel remains open after this message, and - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 6] - -Internet-Draft SSH Connection Protocol Oct 2003 - - - more data may still be sent in the other direction. This message - does not consume window space and can be sent even if no window space - is available. - - When either party wishes to terminate the channel, it sends - SSH_MSG_CHANNEL_CLOSE. Upon receiving this message, a party MUST - send back a SSH_MSG_CHANNEL_CLOSE unless it has already sent this - message for the channel. The channel is considered closed for a - party when it has both sent and received SSH_MSG_CHANNEL_CLOSE, and - the party may then reuse the channel number. A party MAY send - SSH_MSG_CHANNEL_CLOSE without having sent or received - SSH_MSG_CHANNEL_EOF. - - byte SSH_MSG_CHANNEL_CLOSE - uint32 recipient_channel - - This message does not consume window space and can be sent even if no - window space is available. - - It is recommended that any data sent before this message is delivered - to the actual destination, if possible. - -5.4 Channel-Specific Requests - - Many channel types have extensions that are specific to that - particular channel type. An example is requesting a pty (pseudo - terminal) for an interactive session. - - All channel-specific requests use the following format. - - byte SSH_MSG_CHANNEL_REQUEST - uint32 recipient channel - string request type (restricted to US-ASCII) - boolean want reply - ... type-specific data - - If want reply is FALSE, no response will be sent to the request. - Otherwise, the recipient responds with either SSH_MSG_CHANNEL_SUCCESS - or SSH_MSG_CHANNEL_FAILURE, or request-specific continuation - messages. If the request is not recognized or is not supported for - the channel, SSH_MSG_CHANNEL_FAILURE is returned. - - This message does not consume window space and can be sent even if no - window space is available. Request types are local to each channel - type. - - The client is allowed to send further messages without waiting for - the response to the request. - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 7] - -Internet-Draft SSH Connection Protocol Oct 2003 - - - request type names follow the DNS extensibility naming convention - outlined in [SSH-ARCH] - - byte SSH_MSG_CHANNEL_SUCCESS - uint32 recipient_channel - - - byte SSH_MSG_CHANNEL_FAILURE - uint32 recipient_channel - - These messages do not consume window space and can be sent even if no - window space is available. - -6. Interactive Sessions - - A session is a remote execution of a program. The program may be a - shell, an application, a system command, or some built-in subsystem. - It may or may not have a tty, and may or may not involve X11 - forwarding. Multiple sessions can be active simultaneously. - -6.1 Opening a Session - - A session is started by sending the following message. - - byte SSH_MSG_CHANNEL_OPEN - string "session" - uint32 sender channel - uint32 initial window size - uint32 maximum packet size - - Client implementations SHOULD reject any session channel open - requests to make it more difficult for a corrupt server to attack the - client. - -6.2 Requesting a Pseudo-Terminal - - A pseudo-terminal can be allocated for the session by sending the - following message. - - byte SSH_MSG_CHANNEL_REQUEST - uint32 recipient_channel - string "pty-req" - boolean want_reply - string TERM environment variable value (e.g., vt100) - uint32 terminal width, characters (e.g., 80) - uint32 terminal height, rows (e.g., 24) - uint32 terminal width, pixels (e.g., 640) - uint32 terminal height, pixels (e.g., 480) - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 8] - -Internet-Draft SSH Connection Protocol Oct 2003 - - - string encoded terminal modes - - The encoding of terminal modes is described in Section Encoding of - Terminal Modes (Section 8). Zero dimension parameters MUST be - ignored. The character/row dimensions override the pixel dimensions - (when nonzero). Pixel dimensions refer to the drawable area of the - window. - - The dimension parameters are only informational. - - The client SHOULD ignore pty requests. - -6.3 X11 Forwarding - -6.3.1 Requesting X11 Forwarding - - X11 forwarding may be requested for a session by sending - - byte SSH_MSG_CHANNEL_REQUEST - uint32 recipient channel - string "x11-req" - boolean want reply - boolean single connection - string x11 authentication protocol - string x11 authentication cookie - uint32 x11 screen number - - It is recommended that the authentication cookie that is sent be a - fake, random cookie, and that the cookie is checked and replaced by - the real cookie when a connection request is received. - - X11 connection forwarding should stop when the session channel is - closed; however, already opened forwardings should not be - automatically closed when the session channel is closed. - - If `single connection' is TRUE, only a single connection should be - forwarded. No more connections will be forwarded after the first, or - after the session channel has been closed. - - The "x11 authentication protocol" is the name of the X11 - authentication method used, e.g. "MIT-MAGIC-COOKIE-1". - - The x11 authentication cookie MUST be hexadecimal encoded. - - X Protocol is documented in [SCHEIFLER]. - - - - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 9] - -Internet-Draft SSH Connection Protocol Oct 2003 - - -6.3.2 X11 Channels - - X11 channels are opened with a channel open request. The resulting - channels are independent of the session, and closing the session - channel does not close the forwarded X11 channels. - - byte SSH_MSG_CHANNEL_OPEN - string "x11" - uint32 sender channel - uint32 initial window size - uint32 maximum packet size - string originator address (e.g. "192.168.7.38") - uint32 originator port - - The recipient should respond with SSH_MSG_CHANNEL_OPEN_CONFIRMATION - or SSH_MSG_CHANNEL_OPEN_FAILURE. - - Implementations MUST reject any X11 channel open requests if they - have not requested X11 forwarding. - -6.4 Environment Variable Passing - - Environment variables may be passed to the shell/command to be - started later. Uncontrolled setting of environment variables in a - privileged process can be a security hazard. It is recommended that - implementations either maintain a list of allowable variable names or - only set environment variables after the server process has dropped - sufficient privileges. - - byte SSH_MSG_CHANNEL_REQUEST - uint32 recipient channel - string "env" - boolean want reply - string variable name - string variable value - - -6.5 Starting a Shell or a Command - - Once the session has been set up, a program is started at the remote - end. The program can be a shell, an application program or a - subsystem with a host-independent name. Only one of these requests - can succeed per channel. - - byte SSH_MSG_CHANNEL_REQUEST - uint32 recipient channel - string "shell" - boolean want reply - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 10] - -Internet-Draft SSH Connection Protocol Oct 2003 - - - This message will request the user's default shell (typically defined - in /etc/passwd in UNIX systems) to be started at the other end. - - byte SSH_MSG_CHANNEL_REQUEST - uint32 recipient channel - string "exec" - boolean want reply - string command - - This message will request the server to start the execution of the - given command. The command string may contain a path. Normal - precautions MUST be taken to prevent the execution of unauthorized - commands. - - byte SSH_MSG_CHANNEL_REQUEST - uint32 recipient channel - string "subsystem" - boolean want reply - string subsystem name - - This last form executes a predefined subsystem. It is expected that - these will include a general file transfer mechanism, and possibly - other features. Implementations may also allow configuring more such - mechanisms. As the user's shell is usually used to execute the - subsystem, it is advisable for the subsystem protocol to have a - "magic cookie" at the beginning of the protocol transaction to - distinguish it from arbitrary output generated by shell - initialization scripts etc. This spurious output from the shell may - be filtered out either at the server or at the client. - - The server SHOULD not halt the execution of the protocol stack when - starting a shell or a program. All input and output from these SHOULD - be redirected to the channel or to the encrypted tunnel. - - It is RECOMMENDED to request and check the reply for these messages. - The client SHOULD ignore these messages. - - Subsystem names follow the DNS extensibility naming convention - outlined in [SSH-ARCH]. - -6.6 Session Data Transfer - - Data transfer for a session is done using SSH_MSG_CHANNEL_DATA and - SSH_MSG_CHANNEL_EXTENDED_DATA packets and the window mechanism. The - extended data type SSH_EXTENDED_DATA_STDERR has been defined for - stderr data. - - - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 11] - -Internet-Draft SSH Connection Protocol Oct 2003 - - -6.7 Window Dimension Change Message - - When the window (terminal) size changes on the client side, it MAY - send a message to the other side to inform it of the new dimensions. - - byte SSH_MSG_CHANNEL_REQUEST - uint32 recipient_channel - string "window-change" - boolean FALSE - uint32 terminal width, columns - uint32 terminal height, rows - uint32 terminal width, pixels - uint32 terminal height, pixels - - No response SHOULD be sent to this message. - -6.8 Local Flow Control - - On many systems, it is possible to determine if a pseudo-terminal is - using control-S/control-Q flow control. When flow control is - allowed, it is often desirable to do the flow control at the client - end to speed up responses to user requests. This is facilitated by - the following notification. Initially, the server is responsible for - flow control. (Here, again, client means the side originating the - session, and server means the other side.) - - The message below is used by the server to inform the client when it - can or cannot perform flow control (control-S/control-Q processing). - If `client can do' is TRUE, the client is allowed to do flow control - using control-S and control-Q. The client MAY ignore this message. - - byte SSH_MSG_CHANNEL_REQUEST - uint32 recipient channel - string "xon-xoff" - boolean FALSE - boolean client can do - - No response is sent to this message. - -6.9 Signals - - A signal can be delivered to the remote process/service using the - following message. Some systems may not implement signals, in which - case they SHOULD ignore this message. - - byte SSH_MSG_CHANNEL_REQUEST - uint32 recipient channel - string "signal" - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 12] - -Internet-Draft SSH Connection Protocol Oct 2003 - - - boolean FALSE - string signal name without the "SIG" prefix. - - Signal names will be encoded as discussed in the "exit-signal" - SSH_MSG_CHANNEL_REQUEST. - -6.10 Returning Exit Status - - When the command running at the other end terminates, the following - message can be sent to return the exit status of the command. - Returning the status is RECOMMENDED. No acknowledgment is sent for - this message. The channel needs to be closed with - SSH_MSG_CHANNEL_CLOSE after this message. - - The client MAY ignore these messages. - - byte SSH_MSG_CHANNEL_REQUEST - uint32 recipient_channel - string "exit-status" - boolean FALSE - uint32 exit_status - - The remote command may also terminate violently due to a signal. - Such a condition can be indicated by the following message. A zero - exit_status usually means that the command terminated successfully. - - byte SSH_MSG_CHANNEL_REQUEST - uint32 recipient channel - string "exit-signal" - boolean FALSE - string signal name without the "SIG" prefix. - boolean core dumped - string error message (ISO-10646 UTF-8) - string language tag (as defined in [RFC3066]) - - The signal name is one of the following (these are from [POSIX]) - - ABRT - ALRM - FPE - HUP - ILL - INT - KILL - PIPE - QUIT - SEGV - TERM - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 13] - -Internet-Draft SSH Connection Protocol Oct 2003 - - - USR1 - USR2 - - Additional signal names MAY be sent in the format "sig-name@xyz", - where `sig-name' and `xyz' may be anything a particular implementor - wants (except the `@' sign). However, it is suggested that if a - `configure' script is used, the non-standard signal names it finds be - encoded as "[email protected]", where `SIG' is the signal name - without the "SIG" prefix, and `xyz' be the host type, as determined - by `config.guess'. - - The `error message' contains an additional explanation of the error - message. The message may consist of multiple lines. The client - software MAY display this message to the user. If this is done, the - client software should take the precautions discussed in [SSH-ARCH]. - -7. TCP/IP Port Forwarding - -7.1 Requesting Port Forwarding - - A party need not explicitly request forwardings from its own end to - the other direction. However, if it wishes that connections to a - port on the other side be forwarded to the local side, it must - explicitly request this. - - - byte SSH_MSG_GLOBAL_REQUEST - string "tcpip-forward" - boolean want reply - string address to bind (e.g. "0.0.0.0") - uint32 port number to bind - - `Address to bind' and `port number to bind' specify the IP address - and port to which the socket to be listened is bound. The address - should be "0.0.0.0" if connections are allowed from anywhere. (Note - that the client can still filter connections based on information - passed in the open request.) - - Implementations should only allow forwarding privileged ports if the - user has been authenticated as a privileged user. - - Client implementations SHOULD reject these messages; they are - normally only sent by the client. - - - If a client passes 0 as port number to bind and has want reply TRUE - then the server allocates the next available unprivileged port number - and replies with the following message, otherwise there is no - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 14] - -Internet-Draft SSH Connection Protocol Oct 2003 - - - response specific data. - - - byte SSH_MSG_GLOBAL_REQUEST_SUCCESS - uint32 port that was bound on the server - - A port forwarding can be cancelled with the following message. Note - that channel open requests may be received until a reply to this - message is received. - - byte SSH_MSG_GLOBAL_REQUEST - string "cancel-tcpip-forward" - boolean want reply - string address_to_bind (e.g. "127.0.0.1") - uint32 port number to bind - - Client implementations SHOULD reject these messages; they are - normally only sent by the client. - -7.2 TCP/IP Forwarding Channels - - When a connection comes to a port for which remote forwarding has - been requested, a channel is opened to forward the port to the other - side. - - byte SSH_MSG_CHANNEL_OPEN - string "forwarded-tcpip" - uint32 sender channel - uint32 initial window size - uint32 maximum packet size - string address that was connected - uint32 port that was connected - string originator IP address - uint32 originator port - - Implementations MUST reject these messages unless they have - previously requested a remote TCP/IP port forwarding with the given - port number. - - When a connection comes to a locally forwarded TCP/IP port, the - following packet is sent to the other side. Note that these messages - MAY be sent also for ports for which no forwarding has been - explicitly requested. The receiving side must decide whether to - allow the forwarding. - - byte SSH_MSG_CHANNEL_OPEN - string "direct-tcpip" - uint32 sender channel - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 15] - -Internet-Draft SSH Connection Protocol Oct 2003 - - - uint32 initial window size - uint32 maximum packet size - string host to connect - uint32 port to connect - string originator IP address - uint32 originator port - - `Host to connect' and `port to connect' specify the TCP/IP host and - port where the recipient should connect the channel. `Host to - connect' may be either a domain name or a numeric IP address. - - `Originator IP address' is the numeric IP address of the machine - where the connection request comes from, and `originator port' is the - port on the originator host from where the connection came from. - - Forwarded TCP/IP channels are independent of any sessions, and - closing a session channel does not in any way imply that forwarded - connections should be closed. - - Client implementations SHOULD reject direct TCP/IP open requests for - security reasons. - -8. Encoding of Terminal Modes - - Terminal modes (as passed in a pty request) are encoded into a byte - stream. It is intended that the coding be portable across different - environments. - - The tty mode description is a stream of bytes. The stream consists - of opcode-argument pairs. It is terminated by opcode TTY_OP_END (0). - Opcodes 1 to 159 have a single uint32 argument. Opcodes 160 to 255 - are not yet defined, and cause parsing to stop (they should only be - used after any other data). - - The client SHOULD put in the stream any modes it knows about, and the - server MAY ignore any modes it does not know about. This allows some - degree of machine-independence, at least between systems that use a - POSIX-like tty interface. The protocol can support other systems as - well, but the client may need to fill reasonable values for a number - of parameters so the server pty gets set to a reasonable mode (the - server leaves all unspecified mode bits in their default values, and - only some combinations make sense). - - The following opcodes have been defined. The naming of opcodes - mostly follows the POSIX terminal mode flags. - - 0 TTY_OP_END Indicates end of options. - 1 VINTR Interrupt character; 255 if none. Similarly for the - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 16] - -Internet-Draft SSH Connection Protocol Oct 2003 - - - other characters. Not all of these characters are - supported on all systems. - 2 VQUIT The quit character (sends SIGQUIT signal on POSIX - systems). - 3 VERASE Erase the character to left of the cursor. - 4 VKILL Kill the current input line. - 5 VEOF End-of-file character (sends EOF from the terminal). - 6 VEOL End-of-line character in addition to carriage return - and/or linefeed. - 7 VEOL2 Additional end-of-line character. - 8 VSTART Continues paused output (normally control-Q). - 9 VSTOP Pauses output (normally control-S). - 10 VSUSP Suspends the current program. - 11 VDSUSP Another suspend character. - 12 VREPRINT Reprints the current input line. - 13 VWERASE Erases a word left of cursor. - 14 VLNEXT Enter the next character typed literally, even if it - is a special character - 15 VFLUSH Character to flush output. - 16 VSWTCH Switch to a different shell layer. - 17 VSTATUS Prints system status line (load, command, pid etc). - 18 VDISCARD Toggles the flushing of terminal output. - 30 IGNPAR The ignore parity flag. The parameter SHOULD be 0 if - this flag is FALSE set, and 1 if it is TRUE. - 31 PARMRK Mark parity and framing errors. - 32 INPCK Enable checking of parity errors. - 33 ISTRIP Strip 8th bit off characters. - 34 INLCR Map NL into CR on input. - 35 IGNCR Ignore CR on input. - 36 ICRNL Map CR to NL on input. - 37 IUCLC Translate uppercase characters to lowercase. - 38 IXON Enable output flow control. - 39 IXANY Any char will restart after stop. - 40 IXOFF Enable input flow control. - 41 IMAXBEL Ring bell on input queue full. - 50 ISIG Enable signals INTR, QUIT, [D]SUSP. - 51 ICANON Canonicalize input lines. - 52 XCASE Enable input and output of uppercase characters by - preceding their lowercase equivalents with `\'. - 53 ECHO Enable echoing. - 54 ECHOE Visually erase chars. - 55 ECHOK Kill character discards current line. - 56 ECHONL Echo NL even if ECHO is off. - 57 NOFLSH Don't flush after interrupt. - 58 TOSTOP Stop background jobs from output. - 59 IEXTEN Enable extensions. - 60 ECHOCTL Echo control characters as ^(Char). - 61 ECHOKE Visual erase for line kill. - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 17] - -Internet-Draft SSH Connection Protocol Oct 2003 - - - 62 PENDIN Retype pending input. - 70 OPOST Enable output processing. - 71 OLCUC Convert lowercase to uppercase. - 72 ONLCR Map NL to CR-NL. - 73 OCRNL Translate carriage return to newline (output). - 74 ONOCR Translate newline to carriage return-newline - (output). - 75 ONLRET Newline performs a carriage return (output). - 90 CS7 7 bit mode. - 91 CS8 8 bit mode. - 92 PARENB Parity enable. - 93 PARODD Odd parity, else even. - - 128 TTY_OP_ISPEED Specifies the input baud rate in bits per second. - 129 TTY_OP_OSPEED Specifies the output baud rate in bits per second. - - -9. Summary of Message Numbers - - #define SSH_MSG_GLOBAL_REQUEST 80 - #define SSH_MSG_REQUEST_SUCCESS 81 - #define SSH_MSG_REQUEST_FAILURE 82 - #define SSH_MSG_CHANNEL_OPEN 90 - #define SSH_MSG_CHANNEL_OPEN_CONFIRMATION 91 - #define SSH_MSG_CHANNEL_OPEN_FAILURE 92 - #define SSH_MSG_CHANNEL_WINDOW_ADJUST 93 - #define SSH_MSG_CHANNEL_DATA 94 - #define SSH_MSG_CHANNEL_EXTENDED_DATA 95 - #define SSH_MSG_CHANNEL_EOF 96 - #define SSH_MSG_CHANNEL_CLOSE 97 - #define SSH_MSG_CHANNEL_REQUEST 98 - #define SSH_MSG_CHANNEL_SUCCESS 99 - #define SSH_MSG_CHANNEL_FAILURE 100 - - -10. Security Considerations - - This protocol is assumed to run on top of a secure, authenticated - transport. User authentication and protection against network-level - attacks are assumed to be provided by the underlying protocols. - - It is RECOMMENDED that implementations disable all the potentially - dangerous features (e.g. agent forwarding, X11 forwarding, and TCP/IP - forwarding) if the host key has changed. - - Full security considerations for this protocol are provided in - Section 8 of [SSH-ARCH] - - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 18] - -Internet-Draft SSH Connection Protocol Oct 2003 - - -11. iana cONSiderations - - This document is part of a set, the IANA considerations for the SSH - protocol as defined in [SSH-ARCH], [SSH-TRANS], [SSH-USERAUTH], - [SSH-CONNECT] are detailed in [SSH-NUMBERS]. - -12. Intellectual Property - - The IETF takes no position regarding the validity or scope of any - intellectual property 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; neither does it represent that it - has made any effort to identify any such rights. Information on the - IETF's procedures with respect to rights in standards-track and - standards-related documentation can be found in BCP-11. Copies of - claims of rights made available for publication 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 Secretariat. - - The IETF has been notified of intellectual property rights claimed in - regard to some or all of the specification contained in this - document. For more information consult the online list of claimed - rights. - -Normative References - - [SSH-ARCH] - Ylonen, T., "SSH Protocol Architecture", I-D - draft-ietf-architecture-15.txt, Oct 2003. - - [SSH-TRANS] - Ylonen, T., "SSH Transport Layer Protocol", I-D - draft-ietf-transport-17.txt, Oct 2003. - - [SSH-USERAUTH] - Ylonen, T., "SSH Authentication Protocol", I-D - draft-ietf-userauth-18.txt, Oct 2003. - - [SSH-CONNECT] - Ylonen, T., "SSH Connection Protocol", I-D - draft-ietf-connect-18.txt, Oct 2003. - - [SSH-NUMBERS] - Lehtinen, S. and D. Moffat, "SSH Protocol Assigned - Numbers", I-D draft-ietf-secsh-assignednumbers-05.txt, Oct - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 19] - -Internet-Draft SSH Connection Protocol Oct 2003 - - - 2003. - - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - -Informative References - - [RFC3066] Alvestrand, H., "Tags for the Identification of - Languages", BCP 47, RFC 3066, January 2001. - - [RFC1884] Hinden, R. and S. Deering, "IP Version 6 Addressing - Architecture", RFC 1884, December 1995. - - [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO - 10646", RFC 2279, January 1998. - - [SCHEIFLER] - Scheifler, R., "X Window System : The Complete Reference - to Xlib, X Protocol, Icccm, Xlfd, 3rd edition.", Digital - Press ISBN 1555580882, Feburary 1992. - - [POSIX] ISO/IEC, 9945-1., "Information technology -- Portable - Operating System Interface (POSIX)-Part 1: System - Application Program Interface (API) C Language", ANSI/IEE - Std 1003.1, July 1996. - - -Authors' Addresses - - Tatu Ylonen - SSH Communications Security Corp - Fredrikinkatu 42 - HELSINKI FIN-00100 - Finland - - EMail: [email protected] - - - Darren J. Moffat (editor) - Sun Microsystems, Inc - 17 Network Circle - Menlo Park CA 94025 - USA - - EMail: [email protected] - - - - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 20] - -Internet-Draft SSH Connection Protocol Oct 2003 - - -Intellectual Property Statement - - The IETF takes no position regarding the validity or scope of any - intellectual property 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; neither does it represent that it - has made any effort to identify any such rights. Information on the - IETF's procedures with respect to rights in standards-track and - standards-related documentation can be found in BCP-11. Copies of - claims of rights made available for publication 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 implementors or users of this specification can - be obtained from the IETF Secretariat. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights which may cover technology that may be required to practice - this standard. Please address the information to the IETF Executive - Director. - - The IETF has been notified of intellectual property rights claimed in - regard to some or all of the specification contained in this - document. For more information consult the online list of claimed - rights. - - -Full Copyright Statement - - Copyright (C) The Internet Society (2003). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assignees. - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 21] - -Internet-Draft SSH Connection Protocol Oct 2003 - - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS 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. - - -Acknowledgment - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 22]
\ No newline at end of file diff --git a/lib/ssh/doc/standard/draft-ietf-secsh-filexfer-02.2.ps b/lib/ssh/doc/standard/draft-ietf-secsh-filexfer-02.2.ps deleted file mode 100644 index 06c91bf8cd..0000000000 --- a/lib/ssh/doc/standard/draft-ietf-secsh-filexfer-02.2.ps +++ /dev/null @@ -1,2853 +0,0 @@ -%!PS-Adobe-3.0 -%%BoundingBox: 75 0 595 747 -%%Title: Enscript Output -%%For: Magnus Thoang -%%Creator: GNU enscript 1.6.1 -%%CreationDate: Wed Nov 12 12:26:07 2003 -%%Orientation: Portrait -%%Pages: 15 0 -%%DocumentMedia: A4 595 842 0 () () -%%DocumentNeededResources: (atend) -%%EndComments -%%BeginProlog -%%BeginProcSet: PStoPS 1 15 -userdict begin -[/showpage/erasepage/copypage]{dup where{pop dup load - type/operatortype eq{1 array cvx dup 0 3 index cvx put - bind def}{pop}ifelse}{pop}ifelse}forall -[/letter/legal/executivepage/a4/a4small/b5/com10envelope - /monarchenvelope/c5envelope/dlenvelope/lettersmall/note - /folio/quarto/a5]{dup where{dup wcheck{exch{}put} - {pop{}def}ifelse}{pop}ifelse}forall -/setpagedevice {pop}bind 1 index where{dup wcheck{3 1 roll put} - {pop def}ifelse}{def}ifelse -/PStoPSmatrix matrix currentmatrix def -/PStoPSxform matrix def/PStoPSclip{clippath}def -/defaultmatrix{PStoPSmatrix exch PStoPSxform exch concatmatrix}bind def -/initmatrix{matrix defaultmatrix setmatrix}bind def -/initclip[{matrix currentmatrix PStoPSmatrix setmatrix - [{currentpoint}stopped{$error/newerror false put{newpath}} - {/newpath cvx 3 1 roll/moveto cvx 4 array astore cvx}ifelse] - {[/newpath cvx{/moveto cvx}{/lineto cvx} - {/curveto cvx}{/closepath cvx}pathforall]cvx exch pop} - stopped{$error/errorname get/invalidaccess eq{cleartomark - $error/newerror false put cvx exec}{stop}ifelse}if}bind aload pop - /initclip dup load dup type dup/operatortype eq{pop exch pop} - {dup/arraytype eq exch/packedarraytype eq or - {dup xcheck{exch pop aload pop}{pop cvx}ifelse} - {pop cvx}ifelse}ifelse - {newpath PStoPSclip clip newpath exec setmatrix} bind aload pop]cvx def -/initgraphics{initmatrix newpath initclip 1 setlinewidth - 0 setlinecap 0 setlinejoin []0 setdash 0 setgray - 10 setmiterlimit}bind def -end -%%EndProcSet -%%BeginResource: procset Enscript-Prolog 1.6 1 -% -% Procedures. -% - -/_S { % save current state - /_s save def -} def -/_R { % restore from saved state - _s restore -} def - -/S { % showpage protecting gstate - gsave - showpage - grestore -} bind def - -/MF { % fontname newfontname -> - make a new encoded font - /newfontname exch def - /fontname exch def - - /fontdict fontname findfont def - /newfont fontdict maxlength dict def - - fontdict { - exch - dup /FID eq { - % skip FID pair - pop pop - } { - % copy to the new font dictionary - exch newfont 3 1 roll put - } ifelse - } forall - - newfont /FontName newfontname put - - % insert only valid encoding vectors - encoding_vector length 256 eq { - newfont /Encoding encoding_vector put - } if - - newfontname newfont definefont pop -} def - -/SF { % fontname width height -> - set a new font - /height exch def - /width exch def - - findfont - [width 0 0 height 0 0] makefont setfont -} def - -/SUF { % fontname width height -> - set a new user font - /height exch def - /width exch def - - /F-gs-user-font MF - /F-gs-user-font width height SF -} def - -/M {moveto} bind def -/s {show} bind def - -/Box { % x y w h -> - define box path - /d_h exch def /d_w exch def /d_y exch def /d_x exch def - d_x d_y moveto - d_w 0 rlineto - 0 d_h rlineto - d_w neg 0 rlineto - closepath -} def - -/bgs { % x y height blskip gray str -> - show string with bg color - /str exch def - /gray exch def - /blskip exch def - /height exch def - /y exch def - /x exch def - - gsave - x y blskip sub str stringwidth pop height Box - gray setgray - fill - grestore - x y M str s -} def - -% Highlight bars. -/highlight_bars { % nlines lineheight output_y_margin gray -> - - gsave - setgray - /ymarg exch def - /lineheight exch def - /nlines exch def - - % This 2 is just a magic number to sync highlight lines to text. - 0 d_header_y ymarg sub 2 sub translate - - /cw d_output_w cols div def - /nrows d_output_h ymarg 2 mul sub lineheight div cvi def - - % for each column - 0 1 cols 1 sub { - cw mul /xp exch def - - % for each rows - 0 1 nrows 1 sub { - /rn exch def - rn lineheight mul neg /yp exch def - rn nlines idiv 2 mod 0 eq { - % Draw highlight bar. 4 is just a magic indentation. - xp 4 add yp cw 8 sub lineheight neg Box fill - } if - } for - } for - - grestore -} def - -% Line highlight bar. -/line_highlight { % x y width height gray -> - - gsave - /gray exch def - Box gray setgray fill - grestore -} def - -% Column separator lines. -/column_lines { - gsave - .1 setlinewidth - 0 d_footer_h translate - /cw d_output_w cols div def - 1 1 cols 1 sub { - cw mul 0 moveto - 0 d_output_h rlineto stroke - } for - grestore -} def - -% Column borders. -/column_borders { - gsave - .1 setlinewidth - 0 d_footer_h moveto - 0 d_output_h rlineto - d_output_w 0 rlineto - 0 d_output_h neg rlineto - closepath stroke - grestore -} def - -% Do the actual underlay drawing -/draw_underlay { - ul_style 0 eq { - ul_str true charpath stroke - } { - ul_str show - } ifelse -} def - -% Underlay -/underlay { % - -> - - gsave - 0 d_page_h translate - d_page_h neg d_page_w atan rotate - - ul_gray setgray - ul_font setfont - /dw d_page_h dup mul d_page_w dup mul add sqrt def - ul_str stringwidth pop dw exch sub 2 div ul_h_ptsize -2 div moveto - draw_underlay - grestore -} def - -/user_underlay { % - -> - - gsave - ul_x ul_y translate - ul_angle rotate - ul_gray setgray - ul_font setfont - 0 0 ul_h_ptsize 2 div sub moveto - draw_underlay - grestore -} def - -% Page prefeed -/page_prefeed { % bool -> - - statusdict /prefeed known { - statusdict exch /prefeed exch put - } { - pop - } ifelse -} def - -% Wrapped line markers -/wrapped_line_mark { % x y charwith charheight type -> - - /type exch def - /h exch def - /w exch def - /y exch def - /x exch def - - type 2 eq { - % Black boxes (like TeX does) - gsave - 0 setlinewidth - x w 4 div add y M - 0 h rlineto w 2 div 0 rlineto 0 h neg rlineto - closepath fill - grestore - } { - type 3 eq { - % Small arrows - gsave - .2 setlinewidth - x w 2 div add y h 2 div add M - w 4 div 0 rlineto - x w 4 div add y lineto stroke - - x w 4 div add w 8 div add y h 4 div add M - x w 4 div add y lineto - w 4 div h 8 div rlineto stroke - grestore - } { - % do nothing - } ifelse - } ifelse -} def - -% EPSF import. - -/BeginEPSF { - /b4_Inc_state save def % Save state for cleanup - /dict_count countdictstack def % Count objects on dict stack - /op_count count 1 sub def % Count objects on operand stack - userdict begin - /showpage { } def - 0 setgray 0 setlinecap - 1 setlinewidth 0 setlinejoin - 10 setmiterlimit [ ] 0 setdash newpath - /languagelevel where { - pop languagelevel - 1 ne { - false setstrokeadjust false setoverprint - } if - } if -} bind def - -/EndEPSF { - count op_count sub { pos } repeat % Clean up stacks - countdictstack dict_count sub { end } repeat - b4_Inc_state restore -} bind def - -% Check PostScript language level. -/languagelevel where { - pop /gs_languagelevel languagelevel def -} { - /gs_languagelevel 1 def -} ifelse -%%EndResource -%%BeginResource: procset Enscript-Encoding-88591 1.6 1 -/encoding_vector [ -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/space /exclam /quotedbl /numbersign -/dollar /percent /ampersand /quoteright -/parenleft /parenright /asterisk /plus -/comma /hyphen /period /slash -/zero /one /two /three -/four /five /six /seven -/eight /nine /colon /semicolon -/less /equal /greater /question -/at /A /B /C -/D /E /F /G -/H /I /J /K -/L /M /N /O -/P /Q /R /S -/T /U /V /W -/X /Y /Z /bracketleft -/backslash /bracketright /asciicircum /underscore -/quoteleft /a /b /c -/d /e /f /g -/h /i /j /k -/l /m /n /o -/p /q /r /s -/t /u /v /w -/x /y /z /braceleft -/bar /braceright /tilde /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/space /exclamdown /cent /sterling -/currency /yen /brokenbar /section -/dieresis /copyright /ordfeminine /guillemotleft -/logicalnot /hyphen /registered /macron -/degree /plusminus /twosuperior /threesuperior -/acute /mu /paragraph /bullet -/cedilla /onesuperior /ordmasculine /guillemotright -/onequarter /onehalf /threequarters /questiondown -/Agrave /Aacute /Acircumflex /Atilde -/Adieresis /Aring /AE /Ccedilla -/Egrave /Eacute /Ecircumflex /Edieresis -/Igrave /Iacute /Icircumflex /Idieresis -/Eth /Ntilde /Ograve /Oacute -/Ocircumflex /Otilde /Odieresis /multiply -/Oslash /Ugrave /Uacute /Ucircumflex -/Udieresis /Yacute /Thorn /germandbls -/agrave /aacute /acircumflex /atilde -/adieresis /aring /ae /ccedilla -/egrave /eacute /ecircumflex /edieresis -/igrave /iacute /icircumflex /idieresis -/eth /ntilde /ograve /oacute -/ocircumflex /otilde /odieresis /divide -/oslash /ugrave /uacute /ucircumflex -/udieresis /yacute /thorn /ydieresis -] def -%%EndResource -%%EndProlog -%%BeginSetup -%%IncludeResource: font Courier-Bold -%%IncludeResource: font Courier -/HFpt_w 10 def -/HFpt_h 10 def -/Courier-Bold /HF-gs-font MF -/HF /HF-gs-font findfont [HFpt_w 0 0 HFpt_h 0 0] makefont def -/Courier /F-gs-font MF -/F-gs-font 10 10 SF -/#copies 1 def -/d_page_w 520 def -/d_page_h 747 def -/d_header_x 0 def -/d_header_y 747 def -/d_header_w 520 def -/d_header_h 0 def -/d_footer_x 0 def -/d_footer_y 0 def -/d_footer_w 520 def -/d_footer_h 0 def -/d_output_w 520 def -/d_output_h 747 def -/cols 1 def -userdict/PStoPSxform PStoPSmatrix matrix currentmatrix - matrix invertmatrix matrix concatmatrix - matrix invertmatrix put -%%EndSetup -%%Page: (0,1) 1 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 1 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 701 M -(Network Working Group T. Ylonen) s -5 690 M -(Internet-Draft S. Lehtinen) s -5 679 M -(Expires: April 1, 2002 SSH Communications Security Corp) s -5 668 M -( October 2001) s -5 635 M -( SSH File Transfer Protocol) s -5 624 M -( draft-ietf-secsh-filexfer-02.txt) s -5 602 M -(Status of this Memo) s -5 580 M -( This document is an Internet-Draft and is in full conformance with) s -5 569 M -( all provisions of Section 10 of RFC2026.) s -5 547 M -( Internet-Drafts are working documents of the Internet Engineering) s -5 536 M -( Task Force \(IETF\), its areas, and its working groups. Note that) s -5 525 M -( other groups may also distribute working documents as Internet-) s -5 514 M -( Drafts.) s -5 492 M -( Internet-Drafts are draft documents valid for a maximum of six months) s -5 481 M -( and may be updated, replaced, or obsoleted by other documents at any) s -5 470 M -( time. It is inappropriate to use Internet-Drafts as reference) s -5 459 M -( material or to cite them other than as "work in progress.") s -5 437 M -( The list of current Internet-Drafts can be accessed at http://) s -5 426 M -( www.ietf.org/ietf/1id-abstracts.txt.) s -5 404 M -( The list of Internet-Draft Shadow Directories can be accessed at) s -5 393 M -( http://www.ietf.org/shadow.html.) s -5 371 M -( This Internet-Draft will expire on April 1, 2002.) s -5 349 M -(Copyright Notice) s -5 327 M -( Copyright \(C\) The Internet Society \(2001\). All Rights Reserved.) s -5 305 M -(Abstract) s -5 283 M -( The SSH File Transfer Protocol provides secure file transfer) s -5 272 M -( functionality over any reliable data stream. It is the standard file) s -5 261 M -( transfer protocol for use with the SSH2 protocol. This document) s -5 250 M -( describes the file transfer protocol and its interface to the SSH2) s -5 239 M -( protocol suite.) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 1]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 2 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -(Table of Contents) s -5 668 M -( 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3) s -5 657 M -( 2. Use with the SSH Connection Protocol . . . . . . . . . . . . 4) s -5 646 M -( 3. General Packet Format . . . . . . . . . . . . . . . . . . . 5) s -5 635 M -( 4. Protocol Initialization . . . . . . . . . . . . . . . . . . 7) s -5 624 M -( 5. File Attributes . . . . . . . . . . . . . . . . . . . . . . 8) s -5 613 M -( 6. Requests From the Client to the Server . . . . . . . . . . . 10) s -5 602 M -( 6.1 Request Synchronization and Reordering . . . . . . . . . . . 10) s -5 591 M -( 6.2 File Names . . . . . . . . . . . . . . . . . . . . . . . . . 11) s -5 580 M -( 6.3 Opening, Creating, and Closing Files . . . . . . . . . . . . 11) s -5 569 M -( 6.4 Reading and Writing . . . . . . . . . . . . . . . . . . . . 13) s -5 558 M -( 6.5 Removing and Renaming Files . . . . . . . . . . . . . . . . 14) s -5 547 M -( 6.6 Creating and Deleting Directories . . . . . . . . . . . . . 15) s -5 536 M -( 6.7 Scanning Directories . . . . . . . . . . . . . . . . . . . . 15) s -5 525 M -( 6.8 Retrieving File Attributes . . . . . . . . . . . . . . . . . 16) s -5 514 M -( 6.9 Setting File Attributes . . . . . . . . . . . . . . . . . . 17) s -5 503 M -( 6.10 Dealing with Symbolic links . . . . . . . . . . . . . . . . 18) s -5 492 M -( 6.11 Canonicalizing the Server-Side Path Name . . . . . . . . . . 18) s -5 481 M -( 7. Responses from the Server to the Client . . . . . . . . . . 20) s -5 470 M -( 8. Vendor-Specific Extensions . . . . . . . . . . . . . . . . . 24) s -5 459 M -( 9. Security Considerations . . . . . . . . . . . . . . . . . . 25) s -5 448 M -( 10. Changes from previous protocol versions . . . . . . . . . . 26) s -5 437 M -( 10.1 Changes between versions 3 and 2 . . . . . . . . . . . . . . 26) s -5 426 M -( 10.2 Changes between versions 2 and 1 . . . . . . . . . . . . . . 26) s -5 415 M -( 10.3 Changes between versions 1 and 0 . . . . . . . . . . . . . . 26) s -5 404 M -( 11. Trademark Issues . . . . . . . . . . . . . . . . . . . . . . 27) s -5 393 M -( References . . . . . . . . . . . . . . . . . . . . . . . . . 28) s -5 382 M -( Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 28) s -5 371 M -( Full Copyright Statement . . . . . . . . . . . . . . . . . . 29) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 2]) s -_R -S -PStoPSsaved restore -%%Page: (2,3) 2 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 3 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -(1. Introduction) s -5 668 M -( This protocol provides secure file transfer \(and more generally file) s -5 657 M -( system access\) functionality over a reliable data stream, such as a) s -5 646 M -( channel in the SSH2 protocol [3].) s -5 624 M -( This protocol is designed so that it could be used to implement a) s -5 613 M -( secure remote file system service, as well as a secure file transfer) s -5 602 M -( service.) s -5 580 M -( This protocol assumes that it runs over a secure channel, and that) s -5 569 M -( the server has already authenticated the user at the client end, and) s -5 558 M -( that the identity of the client user is externally available to the) s -5 547 M -( server implementation.) s -5 525 M -( In general, this protocol follows a simple request-response model.) s -5 514 M -( Each request and response contains a sequence number and multiple) s -5 503 M -( requests may be pending simultaneously. There are a relatively large) s -5 492 M -( number of different request messages, but a small number of possible) s -5 481 M -( response messages. Each request has one or more response messages) s -5 470 M -( that may be returned in result \(e.g., a read either returns data or) s -5 459 M -( reports error status\).) s -5 437 M -( The packet format descriptions in this specification follow the) s -5 426 M -( notation presented in the secsh architecture draft.[3].) s -5 404 M -( Even though this protocol is described in the context of the SSH2) s -5 393 M -( protocol, this protocol is general and independent of the rest of the) s -5 382 M -( SSH2 protocol suite. It could be used in a number of different) s -5 371 M -( applications, such as secure file transfer over TLS RFC 2246 [1] and) s -5 360 M -( transfer of management information in VPN applications.) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 3]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 4 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -(2. Use with the SSH Connection Protocol) s -5 668 M -( When used with the SSH2 Protocol suite, this protocol is intended to) s -5 657 M -( be used from the SSH Connection Protocol [5] as a subsystem, as) s -5 646 M -( described in section ``Starting a Shell or a Command''. The) s -5 635 M -( subsystem name used with this protocol is "sftp".) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 4]) s -_R -S -PStoPSsaved restore -%%Page: (4,5) 3 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 5 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -(3. General Packet Format) s -5 668 M -( All packets transmitted over the secure connection are of the) s -5 657 M -( following format:) s -5 635 M -( uint32 length) s -5 624 M -( byte type) s -5 613 M -( byte[length - 1] data payload) s -5 591 M -( That is, they are just data preceded by 32-bit length and 8-bit type) s -5 580 M -( fields. The `length' is the length of the data area, and does not) s -5 569 M -( include the `length' field itself. The format and interpretation of) s -5 558 M -( the data area depends on the packet type.) s -5 536 M -( All packet descriptions below only specify the packet type and the) s -5 525 M -( data that goes into the data field. Thus, they should be prefixed by) s -5 514 M -( the `length' and `type' fields.) s -5 492 M -( The maximum size of a packet is in practice determined by the client) s -5 481 M -( \(the maximum size of read or write requests that it sends, plus a few) s -5 470 M -( bytes of packet overhead\). All servers SHOULD support packets of at) s -5 459 M -( least 34000 bytes \(where the packet size refers to the full length,) s -5 448 M -( including the header above\). This should allow for reads and writes) s -5 437 M -( of at most 32768 bytes.) s -5 415 M -( There is no limit on the number of outstanding \(non-acknowledged\)) s -5 404 M -( requests that the client may send to the server. In practice this is) s -5 393 M -( limited by the buffering available on the data stream and the queuing) s -5 382 M -( performed by the server. If the server's queues are full, it should) s -5 371 M -( not read any more data from the stream, and flow control will prevent) s -5 360 M -( the client from sending more requests. Note, however, that while) s -5 349 M -( there is no restriction on the protocol level, the client's API may) s -5 338 M -( provide a limit in order to prevent infinite queuing of outgoing) s -5 327 M -( requests at the client.) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 5]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 6 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -( The following values are defined for packet types.) s -5 668 M -( #define SSH_FXP_INIT 1) s -5 657 M -( #define SSH_FXP_VERSION 2) s -5 646 M -( #define SSH_FXP_OPEN 3) s -5 635 M -( #define SSH_FXP_CLOSE 4) s -5 624 M -( #define SSH_FXP_READ 5) s -5 613 M -( #define SSH_FXP_WRITE 6) s -5 602 M -( #define SSH_FXP_LSTAT 7) s -5 591 M -( #define SSH_FXP_FSTAT 8) s -5 580 M -( #define SSH_FXP_SETSTAT 9) s -5 569 M -( #define SSH_FXP_FSETSTAT 10) s -5 558 M -( #define SSH_FXP_OPENDIR 11) s -5 547 M -( #define SSH_FXP_READDIR 12) s -5 536 M -( #define SSH_FXP_REMOVE 13) s -5 525 M -( #define SSH_FXP_MKDIR 14) s -5 514 M -( #define SSH_FXP_RMDIR 15) s -5 503 M -( #define SSH_FXP_REALPATH 16) s -5 492 M -( #define SSH_FXP_STAT 17) s -5 481 M -( #define SSH_FXP_RENAME 18) s -5 470 M -( #define SSH_FXP_READLINK 19) s -5 459 M -( #define SSH_FXP_SYMLINK 20) s -5 448 M -( #define SSH_FXP_STATUS 101) s -5 437 M -( #define SSH_FXP_HANDLE 102) s -5 426 M -( #define SSH_FXP_DATA 103) s -5 415 M -( #define SSH_FXP_NAME 104) s -5 404 M -( #define SSH_FXP_ATTRS 105) s -5 393 M -( #define SSH_FXP_EXTENDED 200) s -5 382 M -( #define SSH_FXP_EXTENDED_REPLY 201) s -5 360 M -( Additional packet types should only be defined if the protocol) s -5 349 M -( version number \(see Section ``Protocol Initialization''\) is) s -5 338 M -( incremented, and their use MUST be negotiated using the version) s -5 327 M -( number. However, the SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY) s -5 316 M -( packets can be used to implement vendor-specific extensions. See) s -5 305 M -( Section ``Vendor-Specific-Extensions'' for more details.) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 6]) s -_R -S -PStoPSsaved restore -%%Page: (6,7) 4 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 7 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -(4. Protocol Initialization) s -5 668 M -( When the file transfer protocol starts, it first sends a SSH_FXP_INIT) s -5 657 M -( \(including its version number\) packet to the server. The server) s -5 646 M -( responds with a SSH_FXP_VERSION packet, supplying the lowest of its) s -5 635 M -( own and the client's version number. Both parties should from then) s -5 624 M -( on adhere to particular version of the protocol.) s -5 602 M -( The SSH_FXP_INIT packet \(from client to server\) has the following) s -5 591 M -( data:) s -5 569 M -( uint32 version) s -5 558 M -( <extension data>) s -5 536 M -( The SSH_FXP_VERSION packet \(from server to client\) has the following) s -5 525 M -( data:) s -5 503 M -( uint32 version) s -5 492 M -( <extension data>) s -5 470 M -( The version number of the protocol specified in this document is 3.) s -5 459 M -( The version number should be incremented for each incompatible) s -5 448 M -( revision of this protocol.) s -5 426 M -( The extension data in the above packets may be empty, or may be a) s -5 415 M -( sequence of) s -5 393 M -( string extension_name) s -5 382 M -( string extension_data) s -5 360 M -( pairs \(both strings MUST always be present if one is, but the) s -5 349 M -( `extension_data' string may be of zero length\). If present, these) s -5 338 M -( strings indicate extensions to the baseline protocol. The) s -5 327 M -( `extension_name' field\(s\) identify the name of the extension. The) s -5 316 M -( name should be of the form "name@domain", where the domain is the DNS) s -5 305 M -( domain name of the organization defining the extension. Additional) s -5 294 M -( names that are not of this format may be defined later by the IETF.) s -5 283 M -( Implementations MUST silently ignore any extensions whose name they) s -5 272 M -( do not recognize.) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 7]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 8 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -(5. File Attributes) s -5 668 M -( A new compound data type is defined for encoding file attributes. It) s -5 657 M -( is basically just a combination of elementary types, but is defined) s -5 646 M -( once because of the non-trivial description of the fields and to) s -5 635 M -( ensure maintainability.) s -5 613 M -( The same encoding is used both when returning file attributes from) s -5 602 M -( the server and when sending file attributes to the server. When) s -5 591 M -( sending it to the server, the flags field specifies which attributes) s -5 580 M -( are included, and the server will use default values for the) s -5 569 M -( remaining attributes \(or will not modify the values of remaining) s -5 558 M -( attributes\). When receiving attributes from the server, the flags) s -5 547 M -( specify which attributes are included in the returned data. The) s -5 536 M -( server normally returns all attributes it knows about.) s -5 514 M -( uint32 flags) s -5 503 M -( uint64 size present only if flag SSH_FILEXFER_ATTR_SIZE) s -5 492 M -( uint32 uid present only if flag SSH_FILEXFER_ATTR_UIDGID) s -5 481 M -( uint32 gid present only if flag SSH_FILEXFER_ATTR_UIDGID) s -5 470 M -( uint32 permissions present only if flag SSH_FILEXFER_ATTR_PERMISSIONS) s -5 459 M -( uint32 atime present only if flag SSH_FILEXFER_ACMODTIME) s -5 448 M -( uint32 mtime present only if flag SSH_FILEXFER_ACMODTIME) s -5 437 M -( uint32 extended_count present only if flag SSH_FILEXFER_ATTR_EXTENDED) s -5 426 M -( string extended_type) s -5 415 M -( string extended_data) s -5 404 M -( ... more extended data \(extended_type - extended_data pairs\),) s -5 393 M -( so that number of pairs equals extended_count) s -5 371 M -( The `flags' specify which of the fields are present. Those fields) s -5 360 M -( for which the corresponding flag is not set are not present \(not) s -5 349 M -( included in the packet\). New flags can only be added by incrementing) s -5 338 M -( the protocol version number \(or by using the extension mechanism) s -5 327 M -( described below\).) s -5 305 M -( The `size' field specifies the size of the file in bytes.) s -5 283 M -( The `uid' and `gid' fields contain numeric Unix-like user and group) s -5 272 M -( identifiers, respectively.) s -5 250 M -( The `permissions' field contains a bit mask of file permissions as) s -5 239 M -( defined by posix [1].) s -5 217 M -( The `atime' and `mtime' contain the access and modification times of) s -5 206 M -( the files, respectively. They are represented as seconds from Jan 1,) s -5 195 M -( 1970 in UTC.) s -5 173 M -( The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 8]) s -_R -S -PStoPSsaved restore -%%Page: (8,9) 5 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 9 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -( mechanism for vendor-specific extensions. If the flag is specified,) s -5 679 M -( then the `extended_count' field is present. It specifies the number) s -5 668 M -( of extended_type-extended_data pairs that follow. Each of these) s -5 657 M -( pairs specifies an extended attribute. For each of the attributes,) s -5 646 M -( the extended_type field should be a string of the format) s -5 635 M -( "name@domain", where "domain" is a valid, registered domain name and) s -5 624 M -( "name" identifies the method. The IETF may later standardize certain) s -5 613 M -( names that deviate from this format \(e.g., that do not contain the) s -5 602 M -( "@" sign\). The interpretation of `extended_data' depends on the) s -5 591 M -( type. Implementations SHOULD ignore extended data fields that they) s -5 580 M -( do not understand.) s -5 558 M -( Additional fields can be added to the attributes by either defining) s -5 547 M -( additional bits to the flags field to indicate their presence, or by) s -5 536 M -( defining extended attributes for them. The extended attributes) s -5 525 M -( mechanism is recommended for most purposes; additional flags bits) s -5 514 M -( should only be defined by an IETF standards action that also) s -5 503 M -( increments the protocol version number. The use of such new fields) s -5 492 M -( MUST be negotiated by the version number in the protocol exchange.) s -5 481 M -( It is a protocol error if a packet with unsupported protocol bits is) s -5 470 M -( received.) s -5 448 M -( The flags bits are defined to have the following values:) s -5 426 M -( #define SSH_FILEXFER_ATTR_SIZE 0x00000001) s -5 415 M -( #define SSH_FILEXFER_ATTR_UIDGID 0x00000002) s -5 404 M -( #define SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004) s -5 393 M -( #define SSH_FILEXFER_ATTR_ACMODTIME 0x00000008) s -5 382 M -( #define SSH_FILEXFER_ATTR_EXTENDED 0x80000000) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 9]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 10 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -(6. Requests From the Client to the Server) s -5 668 M -( Requests from the client to the server represent the various file) s -5 657 M -( system operations. Each request begins with an `id' field, which is) s -5 646 M -( a 32-bit identifier identifying the request \(selected by the client\).) s -5 635 M -( The same identifier will be returned in the response to the request.) s -5 624 M -( One possible implementation of it is a monotonically increasing) s -5 613 M -( request sequence number \(modulo 2^32\).) s -5 591 M -( Many operations in the protocol operate on open files. The) s -5 580 M -( SSH_FXP_OPEN request can return a file handle \(which is an opaque) s -5 569 M -( variable-length string\) which may be used to access the file later) s -5 558 M -( \(e.g. in a read operation\). The client MUST NOT send requests the) s -5 547 M -( server with bogus or closed handles. However, the server MUST) s -5 536 M -( perform adequate checks on the handle in order to avoid security) s -5 525 M -( risks due to fabricated handles.) s -5 503 M -( This design allows either stateful and stateless server) s -5 492 M -( implementation, as well as an implementation which caches state) s -5 481 M -( between requests but may also flush it. The contents of the file) s -5 470 M -( handle string are entirely up to the server and its design. The) s -5 459 M -( client should not modify or attempt to interpret the file handle) s -5 448 M -( strings.) s -5 426 M -( The file handle strings MUST NOT be longer than 256 bytes.) s -5 404 M -(6.1 Request Synchronization and Reordering) s -5 382 M -( The protocol and implementations MUST process requests relating to) s -5 371 M -( the same file in the order in which they are received. In other) s -5 360 M -( words, if an application submits multiple requests to the server, the) s -5 349 M -( results in the responses will be the same as if it had sent the) s -5 338 M -( requests one at a time and waited for the response in each case. For) s -5 327 M -( example, the server may process non-overlapping read/write requests) s -5 316 M -( to the same file in parallel, but overlapping reads and writes cannot) s -5 305 M -( be reordered or parallelized. However, there are no ordering) s -5 294 M -( restrictions on the server for processing requests from two different) s -5 283 M -( file transfer connections. The server may interleave and parallelize) s -5 272 M -( them at will.) s -5 250 M -( There are no restrictions on the order in which responses to) s -5 239 M -( outstanding requests are delivered to the client, except that the) s -5 228 M -( server must ensure fairness in the sense that processing of no) s -5 217 M -( request will be indefinitely delayed even if the client is sending) s -5 206 M -( other requests so that there are multiple outstanding requests all) s -5 195 M -( the time.) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 10]) s -_R -S -PStoPSsaved restore -%%Page: (10,11) 6 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 11 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -(6.2 File Names) s -5 668 M -( This protocol represents file names as strings. File names are) s -5 657 M -( assumed to use the slash \('/'\) character as a directory separator.) s -5 635 M -( File names starting with a slash are "absolute", and are relative to) s -5 624 M -( the root of the file system. Names starting with any other character) s -5 613 M -( are relative to the user's default directory \(home directory\). Note) s -5 602 M -( that identifying the user is assumed to take place outside of this) s -5 591 M -( protocol.) s -5 569 M -( Servers SHOULD interpret a path name component ".." as referring to) s -5 558 M -( the parent directory, and "." as referring to the current directory.) s -5 547 M -( If the server implementation limits access to certain parts of the) s -5 536 M -( file system, it must be extra careful in parsing file names when) s -5 525 M -( enforcing such restrictions. There have been numerous reported) s -5 514 M -( security bugs where a ".." in a path name has allowed access outside) s -5 503 M -( the intended area.) s -5 481 M -( An empty path name is valid, and it refers to the user's default) s -5 470 M -( directory \(usually the user's home directory\).) s -5 448 M -( Otherwise, no syntax is defined for file names by this specification.) s -5 437 M -( Clients should not make any other assumptions; however, they can) s -5 426 M -( splice path name components returned by SSH_FXP_READDIR together) s -5 415 M -( using a slash \('/'\) as the separator, and that will work as expected.) s -5 393 M -( It is understood that the lack of well-defined semantics for file) s -5 382 M -( names may cause interoperability problems between clients and servers) s -5 371 M -( using radically different operating systems. However, this approach) s -5 360 M -( is known to work acceptably with most systems, and alternative) s -5 349 M -( approaches that e.g. treat file names as sequences of structured) s -5 338 M -( components are quite complicated.) s -5 316 M -(6.3 Opening, Creating, and Closing Files) s -5 294 M -( Files are opened and created using the SSH_FXP_OPEN message, whose) s -5 283 M -( data part is as follows:) s -5 261 M -( uint32 id) s -5 250 M -( string filename) s -5 239 M -( uint32 pflags) s -5 228 M -( ATTRS attrs) s -5 206 M -( The `id' field is the request identifier as for all requests.) s -5 184 M -( The `filename' field specifies the file name. See Section ``File) s -5 173 M -( Names'' for more information.) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 11]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 12 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -( The `pflags' field is a bitmask. The following bits have been) s -5 679 M -( defined.) s -5 657 M -( #define SSH_FXF_READ 0x00000001) s -5 646 M -( #define SSH_FXF_WRITE 0x00000002) s -5 635 M -( #define SSH_FXF_APPEND 0x00000004) s -5 624 M -( #define SSH_FXF_CREAT 0x00000008) s -5 613 M -( #define SSH_FXF_TRUNC 0x00000010) s -5 602 M -( #define SSH_FXF_EXCL 0x00000020) s -5 580 M -( These have the following meanings:) s -5 558 M -( SSH_FXF_READ) s -5 547 M -( Open the file for reading.) s -5 525 M -( SSH_FXF_WRITE) s -5 514 M -( Open the file for writing. If both this and SSH_FXF_READ are) s -5 503 M -( specified, the file is opened for both reading and writing.) s -5 481 M -( SSH_FXF_APPEND) s -5 470 M -( Force all writes to append data at the end of the file.) s -5 448 M -( SSH_FXF_CREAT) s -5 437 M -( If this flag is specified, then a new file will be created if one) s -5 426 M -( does not already exist \(if O_TRUNC is specified, the new file will) s -5 415 M -( be truncated to zero length if it previously exists\).) s -5 393 M -( SSH_FXF_TRUNC) s -5 382 M -( Forces an existing file with the same name to be truncated to zero) s -5 371 M -( length when creating a file by specifying SSH_FXF_CREAT.) s -5 360 M -( SSH_FXF_CREAT MUST also be specified if this flag is used.) s -5 338 M -( SSH_FXF_EXCL) s -5 327 M -( Causes the request to fail if the named file already exists.) s -5 316 M -( SSH_FXF_CREAT MUST also be specified if this flag is used.) s -5 294 M -( The `attrs' field specifies the initial attributes for the file.) s -5 283 M -( Default values will be used for those attributes that are not) s -5 272 M -( specified. See Section ``File Attributes'' for more information.) s -5 250 M -( Regardless the server operating system, the file will always be) s -5 239 M -( opened in "binary" mode \(i.e., no translations between different) s -5 228 M -( character sets and newline encodings\).) s -5 206 M -( The response to this message will be either SSH_FXP_HANDLE \(if the) s -5 195 M -( operation is successful\) or SSH_FXP_STATUS \(if the operation fails\).) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 12]) s -_R -S -PStoPSsaved restore -%%Page: (12,13) 7 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 13 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -( A file is closed by using the SSH_FXP_CLOSE request. Its data field) s -5 679 M -( has the following format:) s -5 657 M -( uint32 id) s -5 646 M -( string handle) s -5 624 M -( where `id' is the request identifier, and `handle' is a handle) s -5 613 M -( previously returned in the response to SSH_FXP_OPEN or) s -5 602 M -( SSH_FXP_OPENDIR. The handle becomes invalid immediately after this) s -5 591 M -( request has been sent.) s -5 569 M -( The response to this request will be a SSH_FXP_STATUS message. One) s -5 558 M -( should note that on some server platforms even a close can fail.) s -5 547 M -( This can happen e.g. if the server operating system caches writes,) s -5 536 M -( and an error occurs while flushing cached writes during the close.) s -5 514 M -(6.4 Reading and Writing) s -5 492 M -( Once a file has been opened, it can be read using the SSH_FXP_READ) s -5 481 M -( message, which has the following format:) s -5 459 M -( uint32 id) s -5 448 M -( string handle) s -5 437 M -( uint64 offset) s -5 426 M -( uint32 len) s -5 404 M -( where `id' is the request identifier, `handle' is an open file handle) s -5 393 M -( returned by SSH_FXP_OPEN, `offset' is the offset \(in bytes\) relative) s -5 382 M -( to the beginning of the file from where to start reading, and `len') s -5 371 M -( is the maximum number of bytes to read.) s -5 349 M -( In response to this request, the server will read as many bytes as it) s -5 338 M -( can from the file \(up to `len'\), and return them in a SSH_FXP_DATA) s -5 327 M -( message. If an error occurs or EOF is encountered before reading any) s -5 316 M -( data, the server will respond with SSH_FXP_STATUS. For normal disk) s -5 305 M -( files, it is guaranteed that this will read the specified number of) s -5 294 M -( bytes, or up to end of file. For e.g. device files this may return) s -5 283 M -( fewer bytes than requested.) s -5 261 M -( Writing to a file is achieved using the SSH_FXP_WRITE message, which) s -5 250 M -( has the following format:) s -5 228 M -( uint32 id) s -5 217 M -( string handle) s -5 206 M -( uint64 offset) s -5 195 M -( string data) s -5 173 M -( where `id' is a request identifier, `handle' is a file handle) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 13]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 14 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -( returned by SSH_FXP_OPEN, `offset' is the offset \(in bytes\) from the) s -5 679 M -( beginning of the file where to start writing, and `data' is the data) s -5 668 M -( to be written.) s -5 646 M -( The write will extend the file if writing beyond the end of the file.) s -5 635 M -( It is legal to write way beyond the end of the file; the semantics) s -5 624 M -( are to write zeroes from the end of the file to the specified offset) s -5 613 M -( and then the data. On most operating systems, such writes do not) s -5 602 M -( allocate disk space but instead leave "holes" in the file.) s -5 580 M -( The server responds to a write request with a SSH_FXP_STATUS message.) s -5 558 M -(6.5 Removing and Renaming Files) s -5 536 M -( Files can be removed using the SSH_FXP_REMOVE message. It has the) s -5 525 M -( following format:) s -5 503 M -( uint32 id) s -5 492 M -( string filename) s -5 470 M -( where `id' is the request identifier and `filename' is the name of) s -5 459 M -( the file to be removed. See Section ``File Names'' for more) s -5 448 M -( information. This request cannot be used to remove directories.) s -5 426 M -( The server will respond to this request with a SSH_FXP_STATUS) s -5 415 M -( message.) s -5 393 M -( Files \(and directories\) can be renamed using the SSH_FXP_RENAME) s -5 382 M -( message. Its data is as follows:) s -5 360 M -( uint32 id) s -5 349 M -( string oldpath) s -5 338 M -( string newpath) s -5 316 M -( where `id' is the request identifier, `oldpath' is the name of an) s -5 305 M -( existing file or directory, and `newpath' is the new name for the) s -5 294 M -( file or directory. It is an error if there already exists a file) s -5 283 M -( with the name specified by newpath. The server may also fail rename) s -5 272 M -( requests in other situations, for example if `oldpath' and `newpath') s -5 261 M -( point to different file systems on the server.) s -5 239 M -( The server will respond to this request with a SSH_FXP_STATUS) s -5 228 M -( message.) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 14]) s -_R -S -PStoPSsaved restore -%%Page: (14,15) 8 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 15 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -(6.6 Creating and Deleting Directories) s -5 668 M -( New directories can be created using the SSH_FXP_MKDIR request. It) s -5 657 M -( has the following format:) s -5 635 M -( uint32 id) s -5 624 M -( string path) s -5 613 M -( ATTRS attrs) s -5 591 M -( where `id' is the request identifier, `path' and `attrs' specifies) s -5 580 M -( the modifications to be made to its attributes. See Section ``File) s -5 569 M -( Names'' for more information on file names. Attributes are discussed) s -5 558 M -( in more detail in Section ``File Attributes''. specifies the) s -5 547 M -( directory to be created. An error will be returned if a file or) s -5 536 M -( directory with the specified path already exists. The server will) s -5 525 M -( respond to this request with a SSH_FXP_STATUS message.) s -5 503 M -( Directories can be removed using the SSH_FXP_RMDIR request, which) s -5 492 M -( has the following format:) s -5 470 M -( uint32 id) s -5 459 M -( string path) s -5 437 M -( where `id' is the request identifier, and `path' specifies the) s -5 426 M -( directory to be removed. See Section ``File Names'' for more) s -5 415 M -( information on file names. An error will be returned if no directory) s -5 404 M -( with the specified path exists, or if the specified directory is not) s -5 393 M -( empty, or if the path specified a file system object other than a) s -5 382 M -( directory. The server responds to this request with a SSH_FXP_STATUS) s -5 371 M -( message.) s -5 349 M -(6.7 Scanning Directories) s -5 327 M -( The files in a directory can be listed using the SSH_FXP_OPENDIR and) s -5 316 M -( SSH_FXP_READDIR requests. Each SSH_FXP_READDIR request returns one) s -5 305 M -( or more file names with full file attributes for each file. The) s -5 294 M -( client should call SSH_FXP_READDIR repeatedly until it has found the) s -5 283 M -( file it is looking for or until the server responds with a) s -5 272 M -( SSH_FXP_STATUS message indicating an error \(normally SSH_FX_EOF if) s -5 261 M -( there are no more files in the directory\). The client should then) s -5 250 M -( close the handle using the SSH_FXP_CLOSE request.) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 15]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 16 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -( The SSH_FXP_OPENDIR opens a directory for reading. It has the) s -5 679 M -( following format:) s -5 657 M -( uint32 id) s -5 646 M -( string path) s -5 624 M -( where `id' is the request identifier and `path' is the path name of) s -5 613 M -( the directory to be listed \(without any trailing slash\). See Section) s -5 602 M -( ``File Names'' for more information on file names. This will return) s -5 591 M -( an error if the path does not specify a directory or if the directory) s -5 580 M -( is not readable. The server will respond to this request with either) s -5 569 M -( a SSH_FXP_HANDLE or a SSH_FXP_STATUS message.) s -5 547 M -( Once the directory has been successfully opened, files \(and) s -5 536 M -( directories\) contained in it can be listed using SSH_FXP_READDIR) s -5 525 M -( requests. These are of the format) s -5 503 M -( uint32 id) s -5 492 M -( string handle) s -5 470 M -( where `id' is the request identifier, and `handle' is a handle) s -5 459 M -( returned by SSH_FXP_OPENDIR. \(It is a protocol error to attempt to) s -5 448 M -( use an ordinary file handle returned by SSH_FXP_OPEN.\)) s -5 426 M -( The server responds to this request with either a SSH_FXP_NAME or a) s -5 415 M -( SSH_FXP_STATUS message. One or more names may be returned at a time.) s -5 404 M -( Full status information is returned for each name in order to speed) s -5 393 M -( up typical directory listings.) s -5 371 M -( When the client no longer wishes to read more names from the) s -5 360 M -( directory, it SHOULD call SSH_FXP_CLOSE for the handle. The handle) s -5 349 M -( should be closed regardless of whether an error has occurred or not.) s -5 327 M -(6.8 Retrieving File Attributes) s -5 305 M -( Very often, file attributes are automatically returned by) s -5 294 M -( SSH_FXP_READDIR. However, sometimes there is need to specifically) s -5 283 M -( retrieve the attributes for a named file. This can be done using the) s -5 272 M -( SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests.) s -5 250 M -( SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT) s -5 239 M -( follows symbolic links on the server, whereas SSH_FXP_LSTAT does not) s -5 228 M -( follow symbolic links. Both have the same format:) s -5 206 M -( uint32 id) s -5 195 M -( string path) s -5 173 M -( where `id' is the request identifier, and `path' specifies the file) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 16]) s -_R -S -PStoPSsaved restore -%%Page: (16,17) 9 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 17 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -( system object for which status is to be returned. The server) s -5 679 M -( responds to this request with either SSH_FXP_ATTRS or SSH_FXP_STATUS.) s -5 657 M -( SSH_FXP_FSTAT differs from the others in that it returns status) s -5 646 M -( information for an open file \(identified by the file handle\). Its) s -5 635 M -( format is as follows:) s -5 613 M -( uint32 id) s -5 602 M -( string handle) s -5 580 M -( where `id' is the request identifier and `handle' is a file handle) s -5 569 M -( returned by SSH_FXP_OPEN. The server responds to this request with) s -5 558 M -( SSH_FXP_ATTRS or SSH_FXP_STATUS.) s -5 536 M -(6.9 Setting File Attributes) s -5 514 M -( File attributes may be modified using the SSH_FXP_SETSTAT and) s -5 503 M -( SSH_FXP_FSETSTAT requests. These requests are used for operations) s -5 492 M -( such as changing the ownership, permissions or access times, as well) s -5 481 M -( as for truncating a file.) s -5 459 M -( The SSH_FXP_SETSTAT request is of the following format:) s -5 437 M -( uint32 id) s -5 426 M -( string path) s -5 415 M -( ATTRS attrs) s -5 393 M -( where `id' is the request identifier, `path' specifies the file) s -5 382 M -( system object \(e.g. file or directory\) whose attributes are to be) s -5 371 M -( modified, and `attrs' specifies the modifications to be made to its) s -5 360 M -( attributes. Attributes are discussed in more detail in Section) s -5 349 M -( ``File Attributes''.) s -5 327 M -( An error will be returned if the specified file system object does) s -5 316 M -( not exist or the user does not have sufficient rights to modify the) s -5 305 M -( specified attributes. The server responds to this request with a) s -5 294 M -( SSH_FXP_STATUS message.) s -5 272 M -( The SSH_FXP_FSETSTAT request modifies the attributes of a file which) s -5 261 M -( is already open. It has the following format:) s -5 239 M -( uint32 id) s -5 228 M -( string handle) s -5 217 M -( ATTRS attrs) s -5 195 M -( where `id' is the request identifier, `handle' \(MUST be returned by) s -5 184 M -( SSH_FXP_OPEN\) identifies the file whose attributes are to be) s -5 173 M -( modified, and `attrs' specifies the modifications to be made to its) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 17]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 18 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -( attributes. Attributes are discussed in more detail in Section) s -5 679 M -( ``File Attributes''. The server will respond to this request with) s -5 668 M -( SSH_FXP_STATUS.) s -5 646 M -(6.10 Dealing with Symbolic links) s -5 624 M -( The SSH_FXP_READLINK request may be used to read the target of a) s -5 613 M -( symbolic link. It would have a data part as follows:) s -5 591 M -( uint32 id) s -5 580 M -( string path) s -5 558 M -( where `id' is the request identifier and `path' specifies the path) s -5 547 M -( name of the symlink to be read.) s -5 525 M -( The server will respond with a SSH_FXP_NAME packet containing only) s -5 514 M -( one name and a dummy attributes value. The name in the returned) s -5 503 M -( packet contains the target of the link. If an error occurs, the) s -5 492 M -( server may respond with SSH_FXP_STATUS.) s -5 470 M -( The SSH_FXP_SYMLINK request will create a symbolic link on the) s -5 459 M -( server. It is of the following format) s -5 437 M -( uint32 id) s -5 426 M -( string linkpath) s -5 415 M -( string targetpath) s -5 393 M -( where `id' is the request identifier, `linkpath' specifies the path) s -5 382 M -( name of the symlink to be created and `targetpath' specifies the) s -5 371 M -( target of the symlink. The server shall respond with a) s -5 360 M -( SSH_FXP_STATUS indicating either success \(SSH_FX_OK\) or an error) s -5 349 M -( condition.) s -5 327 M -(6.11 Canonicalizing the Server-Side Path Name) s -5 305 M -( The SSH_FXP_REALPATH request can be used to have the server) s -5 294 M -( canonicalize any given path name to an absolute path. This is useful) s -5 283 M -( for converting path names containing ".." components or relative) s -5 272 M -( pathnames without a leading slash into absolute paths. The format of) s -5 261 M -( the request is as follows:) s -5 239 M -( uint32 id) s -5 228 M -( string path) s -5 206 M -( where `id' is the request identifier and `path' specifies the path) s -5 195 M -( name to be canonicalized. The server will respond with a) s -5 184 M -( SSH_FXP_NAME packet containing only one name and a dummy attributes) s -5 173 M -( value. The name is the returned packet will be in canonical form.) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 18]) s -_R -S -PStoPSsaved restore -%%Page: (18,19) 10 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 19 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -( If an error occurs, the server may also respond with SSH_FXP_STATUS.) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 19]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 20 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -(7. Responses from the Server to the Client) s -5 668 M -( The server responds to the client using one of a few response) s -5 657 M -( packets. All requests can return a SSH_FXP_STATUS response upon) s -5 646 M -( failure. When the operation is successful, any of the responses may) s -5 635 M -( be returned \(depending on the operation\). If no data needs to be) s -5 624 M -( returned to the client, the SSH_FXP_STATUS response with SSH_FX_OK) s -5 613 M -( status is appropriate. Otherwise, the SSH_FXP_HANDLE message is used) s -5 602 M -( to return a file handle \(for SSH_FXP_OPEN and SSH_FXP_OPENDIR) s -5 591 M -( requests\), SSH_FXP_DATA is used to return data from SSH_FXP_READ,) s -5 580 M -( SSH_FXP_NAME is used to return one or more file names from a) s -5 569 M -( SSH_FXP_READDIR or SSH_FXP_REALPATH request, and SSH_FXP_ATTRS is) s -5 558 M -( used to return file attributes from SSH_FXP_STAT, SSH_FXP_LSTAT, and) s -5 547 M -( SSH_FXP_FSTAT requests.) s -5 525 M -( Exactly one response will be returned for each request. Each) s -5 514 M -( response packet contains a request identifier which can be used to) s -5 503 M -( match each response with the corresponding request. Note that it is) s -5 492 M -( legal to have several requests outstanding simultaneously, and the) s -5 481 M -( server is allowed to send responses to them in a different order from) s -5 470 M -( the order in which the requests were sent \(the result of their) s -5 459 M -( execution, however, is guaranteed to be as if they had been processed) s -5 448 M -( one at a time in the order in which the requests were sent\).) s -5 426 M -( Response packets are of the same general format as request packets.) s -5 415 M -( Each response packet begins with the request identifier.) s -5 393 M -( The format of the data portion of the SSH_FXP_STATUS response is as) s -5 382 M -( follows:) s -5 360 M -( uint32 id) s -5 349 M -( uint32 error/status code) s -5 338 M -( string error message \(ISO-10646 UTF-8 [RFC-2279]\)) s -5 327 M -( string language tag \(as defined in [RFC-1766]\)) s -5 305 M -( where `id' is the request identifier, and `error/status code') s -5 294 M -( indicates the result of the requested operation. The value SSH_FX_OK) s -5 283 M -( indicates success, and all other values indicate failure.) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 20]) s -_R -S -PStoPSsaved restore -%%Page: (20,21) 11 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 21 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -( Currently, the following values are defined \(other values may be) s -5 679 M -( defined by future versions of this protocol\):) s -5 657 M -( #define SSH_FX_OK 0) s -5 646 M -( #define SSH_FX_EOF 1) s -5 635 M -( #define SSH_FX_NO_SUCH_FILE 2) s -5 624 M -( #define SSH_FX_PERMISSION_DENIED 3) s -5 613 M -( #define SSH_FX_FAILURE 4) s -5 602 M -( #define SSH_FX_BAD_MESSAGE 5) s -5 591 M -( #define SSH_FX_NO_CONNECTION 6) s -5 580 M -( #define SSH_FX_CONNECTION_LOST 7) s -5 569 M -( #define SSH_FX_OP_UNSUPPORTED 8) s -5 547 M -( SSH_FX_OK) s -5 536 M -( Indicates successful completion of the operation.) s -5 514 M -( SSH_FX_EOF) s -5 503 M -( indicates end-of-file condition; for SSH_FX_READ it means that no) s -5 492 M -( more data is available in the file, and for SSH_FX_READDIR it) s -5 481 M -( indicates that no more files are contained in the directory.) s -5 459 M -( SSH_FX_NO_SUCH_FILE) s -5 448 M -( is returned when a reference is made to a file which should exist) s -5 437 M -( but doesn't.) s -5 415 M -( SSH_FX_PERMISSION_DENIED) s -5 404 M -( is returned when the authenticated user does not have sufficient) s -5 393 M -( permissions to perform the operation.) s -5 371 M -( SSH_FX_FAILURE) s -5 360 M -( is a generic catch-all error message; it should be returned if an) s -5 349 M -( error occurs for which there is no more specific error code) s -5 338 M -( defined.) s -5 316 M -( SSH_FX_BAD_MESSAGE) s -5 305 M -( may be returned if a badly formatted packet or protocol) s -5 294 M -( incompatibility is detected.) s -5 272 M -( SSH_FX_NO_CONNECTION) s -5 261 M -( is a pseudo-error which indicates that the client has no) s -5 250 M -( connection to the server \(it can only be generated locally by the) s -5 239 M -( client, and MUST NOT be returned by servers\).) s -5 217 M -( SSH_FX_CONNECTION_LOST) s -5 206 M -( is a pseudo-error which indicates that the connection to the) s -5 195 M -( server has been lost \(it can only be generated locally by the) s -5 184 M -( client, and MUST NOT be returned by servers\).) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 21]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 22 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -( SSH_FX_OP_UNSUPPORTED) s -5 679 M -( indicates that an attempt was made to perform an operation which) s -5 668 M -( is not supported for the server \(it may be generated locally by) s -5 657 M -( the client if e.g. the version number exchange indicates that a) s -5 646 M -( required feature is not supported by the server, or it may be) s -5 635 M -( returned by the server if the server does not implement an) s -5 624 M -( operation\).) s -5 602 M -( The SSH_FXP_HANDLE response has the following format:) s -5 580 M -( uint32 id) s -5 569 M -( string handle) s -5 547 M -( where `id' is the request identifier, and `handle' is an arbitrary) s -5 536 M -( string that identifies an open file or directory on the server. The) s -5 525 M -( handle is opaque to the client; the client MUST NOT attempt to) s -5 514 M -( interpret or modify it in any way. The length of the handle string) s -5 503 M -( MUST NOT exceed 256 data bytes.) s -5 481 M -( The SSH_FXP_DATA response has the following format:) s -5 459 M -( uint32 id) s -5 448 M -( string data) s -5 426 M -( where `id' is the request identifier, and `data' is an arbitrary byte) s -5 415 M -( string containing the requested data. The data string may be at most) s -5 404 M -( the number of bytes requested in a SSH_FXP_READ request, but may also) s -5 393 M -( be shorter if end of file is reached or if the read is from something) s -5 382 M -( other than a regular file.) s -5 360 M -( The SSH_FXP_NAME response has the following format:) s -5 338 M -( uint32 id) s -5 327 M -( uint32 count) s -5 316 M -( repeats count times:) s -5 305 M -( string filename) s -5 294 M -( string longname) s -5 283 M -( ATTRS attrs) s -5 261 M -( where `id' is the request identifier, `count' is the number of names) s -5 250 M -( returned in this response, and the remaining fields repeat `count') s -5 239 M -( times \(so that all three fields are first included for the first) s -5 228 M -( file, then for the second file, etc\). In the repeated part,) s -5 217 M -( `filename' is a file name being returned \(for SSH_FXP_READDIR, it) s -5 206 M -( will be a relative name within the directory, without any path) s -5 195 M -( components; for SSH_FXP_REALPATH it will be an absolute path name\),) s -5 184 M -( `longname' is an expanded format for the file name, similar to what) s -5 173 M -( is returned by "ls -l" on Unix systems, and `attrs' is the attributes) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 22]) s -_R -S -PStoPSsaved restore -%%Page: (22,23) 12 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 23 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -( of the file as described in Section ``File Attributes''.) s -5 668 M -( The format of the `longname' field is unspecified by this protocol.) s -5 657 M -( It MUST be suitable for use in the output of a directory listing) s -5 646 M -( command \(in fact, the recommended operation for a directory listing) s -5 635 M -( command is to simply display this data\). However, clients SHOULD NOT) s -5 624 M -( attempt to parse the longname field for file attributes; they SHOULD) s -5 613 M -( use the attrs field instead.) s -5 591 M -( The recommended format for the longname field is as follows:) s -5 569 M -( -rwxr-xr-x 1 mjos staff 348911 Mar 25 14:29 t-filexfer) s -5 558 M -( 1234567890 123 12345678 12345678 12345678 123456789012) s -5 536 M -( Here, the first line is sample output, and the second field indicates) s -5 525 M -( widths of the various fields. Fields are separated by spaces. The) s -5 514 M -( first field lists file permissions for user, group, and others; the) s -5 503 M -( second field is link count; the third field is the name of the user) s -5 492 M -( who owns the file; the fourth field is the name of the group that) s -5 481 M -( owns the file; the fifth field is the size of the file in bytes; the) s -5 470 M -( sixth field \(which actually may contain spaces, but is fixed to 12) s -5 459 M -( characters\) is the file modification time, and the seventh field is) s -5 448 M -( the file name. Each field is specified to be a minimum of certain) s -5 437 M -( number of character positions \(indicated by the second line above\),) s -5 426 M -( but may also be longer if the data does not fit in the specified) s -5 415 M -( length.) s -5 393 M -( The SSH_FXP_ATTRS response has the following format:) s -5 371 M -( uint32 id) s -5 360 M -( ATTRS attrs) s -5 338 M -( where `id' is the request identifier, and `attrs' is the returned) s -5 327 M -( file attributes as described in Section ``File Attributes''.) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 23]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 24 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -(8. Vendor-Specific Extensions) s -5 668 M -( The SSH_FXP_EXTENDED request provides a generic extension mechanism) s -5 657 M -( for adding vendor-specific commands. The request has the following) s -5 646 M -( format:) s -5 624 M -( uint32 id) s -5 613 M -( string extended-request) s -5 602 M -( ... any request-specific data ...) s -5 580 M -( where `id' is the request identifier, and `extended-request' is a) s -5 569 M -( string of the format "name@domain", where domain is an internet) s -5 558 M -( domain name of the vendor defining the request. The rest of the) s -5 547 M -( request is completely vendor-specific, and servers should only) s -5 536 M -( attempt to interpret it if they recognize the `extended-request') s -5 525 M -( name.) s -5 503 M -( The server may respond to such requests using any of the response) s -5 492 M -( packets defined in Section ``Responses from the Server to the) s -5 481 M -( Client''. Additionally, the server may also respond with a) s -5 470 M -( SSH_FXP_EXTENDED_REPLY packet, as defined below. If the server does) s -5 459 M -( not recognize the `extended-request' name, then the server MUST) s -5 448 M -( respond with SSH_FXP_STATUS with error/status set to) s -5 437 M -( SSH_FX_OP_UNSUPPORTED.) s -5 415 M -( The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary) s -5 404 M -( extension-specific data from the server to the client. It is of the) s -5 393 M -( following format:) s -5 371 M -( uint32 id) s -5 360 M -( ... any request-specific data ...) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 24]) s -_R -S -PStoPSsaved restore -%%Page: (24,25) 13 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 25 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -(9. Security Considerations) s -5 668 M -( This protocol assumes that it is run over a secure channel and that) s -5 657 M -( the endpoints of the channel have been authenticated. Thus, this) s -5 646 M -( protocol assumes that it is externally protected from network-level) s -5 635 M -( attacks.) s -5 613 M -( This protocol provides file system access to arbitrary files on the) s -5 602 M -( server \(only constrained by the server implementation\). It is the) s -5 591 M -( responsibility of the server implementation to enforce any access) s -5 580 M -( controls that may be required to limit the access allowed for any) s -5 569 M -( particular user \(the user being authenticated externally to this) s -5 558 M -( protocol, typically using the SSH User Authentication Protocol [6].) s -5 536 M -( Care must be taken in the server implementation to check the validity) s -5 525 M -( of received file handle strings. The server should not rely on them) s -5 514 M -( directly; it MUST check the validity of each handle before relying on) s -5 503 M -( it.) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 25]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 26 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -(10. Changes from previous protocol versions) s -5 668 M -( The SSH File Transfer Protocol has changed over time, before it's) s -5 657 M -( standardization. The following is a description of the incompatible) s -5 646 M -( changes between different versions.) s -5 624 M -(10.1 Changes between versions 3 and 2) s -5 602 M -( o The SSH_FXP_READLINK and SSH_FXP_SYMLINK messages were added.) s -5 580 M -( o The SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY messages were) s -5 569 M -( added.) s -5 547 M -( o The SSH_FXP_STATUS message was changed to include fields `error) s -5 536 M -( message' and `language tag'.) s -5 503 M -(10.2 Changes between versions 2 and 1) s -5 481 M -( o The SSH_FXP_RENAME message was added.) s -5 448 M -(10.3 Changes between versions 1 and 0) s -5 426 M -( o Implementation changes, no actual protocol changes.) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 26]) s -_R -S -PStoPSsaved restore -%%Page: (26,27) 14 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 27 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -(11. Trademark Issues) s -5 668 M -( "ssh" is a registered trademark of SSH Communications Security Corp) s -5 657 M -( in the United States and/or other countries.) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 27]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 28 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -(References) s -5 668 M -( [1] Dierks, T., Allen, C., Treese, W., Karlton, P., Freier, A. and) s -5 657 M -( P. Kocher, "The TLS Protocol Version 1.0", RFC 2246, January) s -5 646 M -( 1999.) s -5 624 M -( [2] Institute of Electrical and Electronics Engineers, "Information) s -5 613 M -( Technology - Portable Operating System Interface \(POSIX\) - Part) s -5 602 M -( 1: System Application Program Interface \(API\) [C Language]",) s -5 591 M -( IEEE Standard 1003.2, 1996.) s -5 569 M -( [3] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.) s -5 558 M -( Lehtinen, "SSH Protocol Architecture", draft-ietf-secsh-) s -5 547 M -( architecture-09 \(work in progress\), July 2001.) s -5 525 M -( [4] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.) s -5 514 M -( Lehtinen, "SSH Protocol Transport Protocol", draft-ietf-secsh-) s -5 503 M -( architecture-09 \(work in progress\), July 2001.) s -5 481 M -( [5] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.) s -5 470 M -( Lehtinen, "SSH Connection Protocol", draft-ietf-secsh-connect-11) s -5 459 M -( \(work in progress\), July 2001.) s -5 437 M -( [6] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.) s -5 426 M -( Lehtinen, "SSH Authentication Protocol", draft-ietf-secsh-) s -5 415 M -( userauth-11 \(work in progress\), July 2001.) s -5 382 M -(Authors' Addresses) s -5 360 M -( Tatu Ylonen) s -5 349 M -( SSH Communications Security Corp) s -5 338 M -( Fredrikinkatu 42) s -5 327 M -( HELSINKI FIN-00100) s -5 316 M -( Finland) s -5 294 M -( EMail: [email protected]) s -5 261 M -( Sami Lehtinen) s -5 250 M -( SSH Communications Security Corp) s -5 239 M -( Fredrikinkatu 42) s -5 228 M -( HELSINKI FIN-00100) s -5 217 M -( Finland) s -5 195 M -( EMail: [email protected]) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 28]) s -_R -S -PStoPSsaved restore -%%Page: (28,29) 15 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 29 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2001) s -5 690 M -(Full Copyright Statement) s -5 668 M -( Copyright \(C\) The Internet Society \(2001\). All Rights Reserved.) s -5 646 M -( This document and translations of it may be copied and furnished to) s -5 635 M -( others, and derivative works that comment on or otherwise explain it) s -5 624 M -( or assist in its implementation may be prepared, copied, published) s -5 613 M -( and distributed, in whole or in part, without restriction of any) s -5 602 M -( kind, provided that the above copyright notice and this paragraph are) s -5 591 M -( included on all such copies and derivative works. However, this) s -5 580 M -( document itself may not be modified in any way, such as by removing) s -5 569 M -( the copyright notice or references to the Internet Society or other) s -5 558 M -( Internet organizations, except as needed for the purpose of) s -5 547 M -( developing Internet standards in which case the procedures for) s -5 536 M -( copyrights defined in the Internet Standards process must be) s -5 525 M -( followed, or as required to translate it into languages other than) s -5 514 M -( English.) s -5 492 M -( The limited permissions granted above are perpetual and will not be) s -5 481 M -( revoked by the Internet Society or its successors or assigns.) s -5 459 M -( This document and the information contained herein is provided on an) s -5 448 M -( "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING) s -5 437 M -( TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING) s -5 426 M -( BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION) s -5 415 M -( HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF) s -5 404 M -( MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.) s -5 382 M -(Acknowledgement) s -5 360 M -( Funding for the RFC Editor function is currently provided by the) s -5 349 M -( Internet Society.) s -5 129 M -(Ylonen & Lehtinen Expires April 1, 2002 [Page 29]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 30 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -_R -S -PStoPSsaved restore -%%Trailer -%%Pages: 30 -%%DocumentNeededResources: font Courier-Bold Courier -%%EOF diff --git a/lib/ssh/doc/standard/draft-ietf-secsh-filexfer-02.txt b/lib/ssh/doc/standard/draft-ietf-secsh-filexfer-02.txt deleted file mode 100644 index c4ec8c1125..0000000000 --- a/lib/ssh/doc/standard/draft-ietf-secsh-filexfer-02.txt +++ /dev/null @@ -1,1627 +0,0 @@ - - - -Network Working Group T. Ylonen -Internet-Draft S. Lehtinen -Expires: April 1, 2002 SSH Communications Security Corp - October 2001 - - - SSH File Transfer Protocol - draft-ietf-secsh-filexfer-02.txt - -Status of this Memo - - This document is an Internet-Draft and is in full conformance with - all provisions of Section 10 of RFC2026. - - Internet-Drafts are working documents of the Internet Engineering - Task Force (IETF), its areas, and its working groups. Note that - other groups may also distribute working documents as Internet- - Drafts. - - Internet-Drafts are draft documents valid for a maximum of six months - and may be updated, replaced, or obsoleted by other documents at any - time. It is inappropriate to use Internet-Drafts as reference - material or to cite them other than as "work in progress." - - The list of current Internet-Drafts can be accessed at http:// - www.ietf.org/ietf/1id-abstracts.txt. - - The list of Internet-Draft Shadow Directories can be accessed at - http://www.ietf.org/shadow.html. - - This Internet-Draft will expire on April 1, 2002. - -Copyright Notice - - Copyright (C) The Internet Society (2001). All Rights Reserved. - -Abstract - - The SSH File Transfer Protocol provides secure file transfer - functionality over any reliable data stream. It is the standard file - transfer protocol for use with the SSH2 protocol. This document - describes the file transfer protocol and its interface to the SSH2 - protocol suite. - - - - - - - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 1] - -Internet-Draft SSH File Transfer Protocol October 2001 - - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 - 2. Use with the SSH Connection Protocol . . . . . . . . . . . . 4 - 3. General Packet Format . . . . . . . . . . . . . . . . . . . 5 - 4. Protocol Initialization . . . . . . . . . . . . . . . . . . 7 - 5. File Attributes . . . . . . . . . . . . . . . . . . . . . . 8 - 6. Requests From the Client to the Server . . . . . . . . . . . 10 - 6.1 Request Synchronization and Reordering . . . . . . . . . . . 10 - 6.2 File Names . . . . . . . . . . . . . . . . . . . . . . . . . 11 - 6.3 Opening, Creating, and Closing Files . . . . . . . . . . . . 11 - 6.4 Reading and Writing . . . . . . . . . . . . . . . . . . . . 13 - 6.5 Removing and Renaming Files . . . . . . . . . . . . . . . . 14 - 6.6 Creating and Deleting Directories . . . . . . . . . . . . . 15 - 6.7 Scanning Directories . . . . . . . . . . . . . . . . . . . . 15 - 6.8 Retrieving File Attributes . . . . . . . . . . . . . . . . . 16 - 6.9 Setting File Attributes . . . . . . . . . . . . . . . . . . 17 - 6.10 Dealing with Symbolic links . . . . . . . . . . . . . . . . 18 - 6.11 Canonicalizing the Server-Side Path Name . . . . . . . . . . 18 - 7. Responses from the Server to the Client . . . . . . . . . . 20 - 8. Vendor-Specific Extensions . . . . . . . . . . . . . . . . . 24 - 9. Security Considerations . . . . . . . . . . . . . . . . . . 25 - 10. Changes from previous protocol versions . . . . . . . . . . 26 - 10.1 Changes between versions 3 and 2 . . . . . . . . . . . . . . 26 - 10.2 Changes between versions 2 and 1 . . . . . . . . . . . . . . 26 - 10.3 Changes between versions 1 and 0 . . . . . . . . . . . . . . 26 - 11. Trademark Issues . . . . . . . . . . . . . . . . . . . . . . 27 - References . . . . . . . . . . . . . . . . . . . . . . . . . 28 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 28 - Full Copyright Statement . . . . . . . . . . . . . . . . . . 29 - - - - - - - - - - - - - - - - - - - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 2] - -Internet-Draft SSH File Transfer Protocol October 2001 - - -1. Introduction - - This protocol provides secure file transfer (and more generally file - system access) functionality over a reliable data stream, such as a - channel in the SSH2 protocol [3]. - - This protocol is designed so that it could be used to implement a - secure remote file system service, as well as a secure file transfer - service. - - This protocol assumes that it runs over a secure channel, and that - the server has already authenticated the user at the client end, and - that the identity of the client user is externally available to the - server implementation. - - In general, this protocol follows a simple request-response model. - Each request and response contains a sequence number and multiple - requests may be pending simultaneously. There are a relatively large - number of different request messages, but a small number of possible - response messages. Each request has one or more response messages - that may be returned in result (e.g., a read either returns data or - reports error status). - - The packet format descriptions in this specification follow the - notation presented in the secsh architecture draft.[3]. - - Even though this protocol is described in the context of the SSH2 - protocol, this protocol is general and independent of the rest of the - SSH2 protocol suite. It could be used in a number of different - applications, such as secure file transfer over TLS RFC 2246 [1] and - transfer of management information in VPN applications. - - - - - - - - - - - - - - - - - - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 3] - -Internet-Draft SSH File Transfer Protocol October 2001 - - -2. Use with the SSH Connection Protocol - - When used with the SSH2 Protocol suite, this protocol is intended to - be used from the SSH Connection Protocol [5] as a subsystem, as - described in section ``Starting a Shell or a Command''. The - subsystem name used with this protocol is "sftp". - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 4] - -Internet-Draft SSH File Transfer Protocol October 2001 - - -3. General Packet Format - - All packets transmitted over the secure connection are of the - following format: - - uint32 length - byte type - byte[length - 1] data payload - - That is, they are just data preceded by 32-bit length and 8-bit type - fields. The `length' is the length of the data area, and does not - include the `length' field itself. The format and interpretation of - the data area depends on the packet type. - - All packet descriptions below only specify the packet type and the - data that goes into the data field. Thus, they should be prefixed by - the `length' and `type' fields. - - The maximum size of a packet is in practice determined by the client - (the maximum size of read or write requests that it sends, plus a few - bytes of packet overhead). All servers SHOULD support packets of at - least 34000 bytes (where the packet size refers to the full length, - including the header above). This should allow for reads and writes - of at most 32768 bytes. - - There is no limit on the number of outstanding (non-acknowledged) - requests that the client may send to the server. In practice this is - limited by the buffering available on the data stream and the queuing - performed by the server. If the server's queues are full, it should - not read any more data from the stream, and flow control will prevent - the client from sending more requests. Note, however, that while - there is no restriction on the protocol level, the client's API may - provide a limit in order to prevent infinite queuing of outgoing - requests at the client. - - - - - - - - - - - - - - - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 5] - -Internet-Draft SSH File Transfer Protocol October 2001 - - - The following values are defined for packet types. - - #define SSH_FXP_INIT 1 - #define SSH_FXP_VERSION 2 - #define SSH_FXP_OPEN 3 - #define SSH_FXP_CLOSE 4 - #define SSH_FXP_READ 5 - #define SSH_FXP_WRITE 6 - #define SSH_FXP_LSTAT 7 - #define SSH_FXP_FSTAT 8 - #define SSH_FXP_SETSTAT 9 - #define SSH_FXP_FSETSTAT 10 - #define SSH_FXP_OPENDIR 11 - #define SSH_FXP_READDIR 12 - #define SSH_FXP_REMOVE 13 - #define SSH_FXP_MKDIR 14 - #define SSH_FXP_RMDIR 15 - #define SSH_FXP_REALPATH 16 - #define SSH_FXP_STAT 17 - #define SSH_FXP_RENAME 18 - #define SSH_FXP_READLINK 19 - #define SSH_FXP_SYMLINK 20 - #define SSH_FXP_STATUS 101 - #define SSH_FXP_HANDLE 102 - #define SSH_FXP_DATA 103 - #define SSH_FXP_NAME 104 - #define SSH_FXP_ATTRS 105 - #define SSH_FXP_EXTENDED 200 - #define SSH_FXP_EXTENDED_REPLY 201 - - Additional packet types should only be defined if the protocol - version number (see Section ``Protocol Initialization'') is - incremented, and their use MUST be negotiated using the version - number. However, the SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY - packets can be used to implement vendor-specific extensions. See - Section ``Vendor-Specific-Extensions'' for more details. - - - - - - - - - - - - - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 6] - -Internet-Draft SSH File Transfer Protocol October 2001 - - -4. Protocol Initialization - - When the file transfer protocol starts, it first sends a SSH_FXP_INIT - (including its version number) packet to the server. The server - responds with a SSH_FXP_VERSION packet, supplying the lowest of its - own and the client's version number. Both parties should from then - on adhere to particular version of the protocol. - - The SSH_FXP_INIT packet (from client to server) has the following - data: - - uint32 version - <extension data> - - The SSH_FXP_VERSION packet (from server to client) has the following - data: - - uint32 version - <extension data> - - The version number of the protocol specified in this document is 3. - The version number should be incremented for each incompatible - revision of this protocol. - - The extension data in the above packets may be empty, or may be a - sequence of - - string extension_name - string extension_data - - pairs (both strings MUST always be present if one is, but the - `extension_data' string may be of zero length). If present, these - strings indicate extensions to the baseline protocol. The - `extension_name' field(s) identify the name of the extension. The - name should be of the form "name@domain", where the domain is the DNS - domain name of the organization defining the extension. Additional - names that are not of this format may be defined later by the IETF. - Implementations MUST silently ignore any extensions whose name they - do not recognize. - - - - - - - - - - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 7] - -Internet-Draft SSH File Transfer Protocol October 2001 - - -5. File Attributes - - A new compound data type is defined for encoding file attributes. It - is basically just a combination of elementary types, but is defined - once because of the non-trivial description of the fields and to - ensure maintainability. - - The same encoding is used both when returning file attributes from - the server and when sending file attributes to the server. When - sending it to the server, the flags field specifies which attributes - are included, and the server will use default values for the - remaining attributes (or will not modify the values of remaining - attributes). When receiving attributes from the server, the flags - specify which attributes are included in the returned data. The - server normally returns all attributes it knows about. - - uint32 flags - uint64 size present only if flag SSH_FILEXFER_ATTR_SIZE - uint32 uid present only if flag SSH_FILEXFER_ATTR_UIDGID - uint32 gid present only if flag SSH_FILEXFER_ATTR_UIDGID - uint32 permissions present only if flag SSH_FILEXFER_ATTR_PERMISSIONS - uint32 atime present only if flag SSH_FILEXFER_ACMODTIME - uint32 mtime present only if flag SSH_FILEXFER_ACMODTIME - uint32 extended_count present only if flag SSH_FILEXFER_ATTR_EXTENDED - string extended_type - string extended_data - ... more extended data (extended_type - extended_data pairs), - so that number of pairs equals extended_count - - The `flags' specify which of the fields are present. Those fields - for which the corresponding flag is not set are not present (not - included in the packet). New flags can only be added by incrementing - the protocol version number (or by using the extension mechanism - described below). - - The `size' field specifies the size of the file in bytes. - - The `uid' and `gid' fields contain numeric Unix-like user and group - identifiers, respectively. - - The `permissions' field contains a bit mask of file permissions as - defined by posix [1]. - - The `atime' and `mtime' contain the access and modification times of - the files, respectively. They are represented as seconds from Jan 1, - 1970 in UTC. - - The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 8] - -Internet-Draft SSH File Transfer Protocol October 2001 - - - mechanism for vendor-specific extensions. If the flag is specified, - then the `extended_count' field is present. It specifies the number - of extended_type-extended_data pairs that follow. Each of these - pairs specifies an extended attribute. For each of the attributes, - the extended_type field should be a string of the format - "name@domain", where "domain" is a valid, registered domain name and - "name" identifies the method. The IETF may later standardize certain - names that deviate from this format (e.g., that do not contain the - "@" sign). The interpretation of `extended_data' depends on the - type. Implementations SHOULD ignore extended data fields that they - do not understand. - - Additional fields can be added to the attributes by either defining - additional bits to the flags field to indicate their presence, or by - defining extended attributes for them. The extended attributes - mechanism is recommended for most purposes; additional flags bits - should only be defined by an IETF standards action that also - increments the protocol version number. The use of such new fields - MUST be negotiated by the version number in the protocol exchange. - It is a protocol error if a packet with unsupported protocol bits is - received. - - The flags bits are defined to have the following values: - - #define SSH_FILEXFER_ATTR_SIZE 0x00000001 - #define SSH_FILEXFER_ATTR_UIDGID 0x00000002 - #define SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004 - #define SSH_FILEXFER_ATTR_ACMODTIME 0x00000008 - #define SSH_FILEXFER_ATTR_EXTENDED 0x80000000 - - - - - - - - - - - - - - - - - - - - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 9] - -Internet-Draft SSH File Transfer Protocol October 2001 - - -6. Requests From the Client to the Server - - Requests from the client to the server represent the various file - system operations. Each request begins with an `id' field, which is - a 32-bit identifier identifying the request (selected by the client). - The same identifier will be returned in the response to the request. - One possible implementation of it is a monotonically increasing - request sequence number (modulo 2^32). - - Many operations in the protocol operate on open files. The - SSH_FXP_OPEN request can return a file handle (which is an opaque - variable-length string) which may be used to access the file later - (e.g. in a read operation). The client MUST NOT send requests the - server with bogus or closed handles. However, the server MUST - perform adequate checks on the handle in order to avoid security - risks due to fabricated handles. - - This design allows either stateful and stateless server - implementation, as well as an implementation which caches state - between requests but may also flush it. The contents of the file - handle string are entirely up to the server and its design. The - client should not modify or attempt to interpret the file handle - strings. - - The file handle strings MUST NOT be longer than 256 bytes. - -6.1 Request Synchronization and Reordering - - The protocol and implementations MUST process requests relating to - the same file in the order in which they are received. In other - words, if an application submits multiple requests to the server, the - results in the responses will be the same as if it had sent the - requests one at a time and waited for the response in each case. For - example, the server may process non-overlapping read/write requests - to the same file in parallel, but overlapping reads and writes cannot - be reordered or parallelized. However, there are no ordering - restrictions on the server for processing requests from two different - file transfer connections. The server may interleave and parallelize - them at will. - - There are no restrictions on the order in which responses to - outstanding requests are delivered to the client, except that the - server must ensure fairness in the sense that processing of no - request will be indefinitely delayed even if the client is sending - other requests so that there are multiple outstanding requests all - the time. - - - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 10] - -Internet-Draft SSH File Transfer Protocol October 2001 - - -6.2 File Names - - This protocol represents file names as strings. File names are - assumed to use the slash ('/') character as a directory separator. - - File names starting with a slash are "absolute", and are relative to - the root of the file system. Names starting with any other character - are relative to the user's default directory (home directory). Note - that identifying the user is assumed to take place outside of this - protocol. - - Servers SHOULD interpret a path name component ".." as referring to - the parent directory, and "." as referring to the current directory. - If the server implementation limits access to certain parts of the - file system, it must be extra careful in parsing file names when - enforcing such restrictions. There have been numerous reported - security bugs where a ".." in a path name has allowed access outside - the intended area. - - An empty path name is valid, and it refers to the user's default - directory (usually the user's home directory). - - Otherwise, no syntax is defined for file names by this specification. - Clients should not make any other assumptions; however, they can - splice path name components returned by SSH_FXP_READDIR together - using a slash ('/') as the separator, and that will work as expected. - - It is understood that the lack of well-defined semantics for file - names may cause interoperability problems between clients and servers - using radically different operating systems. However, this approach - is known to work acceptably with most systems, and alternative - approaches that e.g. treat file names as sequences of structured - components are quite complicated. - -6.3 Opening, Creating, and Closing Files - - Files are opened and created using the SSH_FXP_OPEN message, whose - data part is as follows: - - uint32 id - string filename - uint32 pflags - ATTRS attrs - - The `id' field is the request identifier as for all requests. - - The `filename' field specifies the file name. See Section ``File - Names'' for more information. - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 11] - -Internet-Draft SSH File Transfer Protocol October 2001 - - - The `pflags' field is a bitmask. The following bits have been - defined. - - #define SSH_FXF_READ 0x00000001 - #define SSH_FXF_WRITE 0x00000002 - #define SSH_FXF_APPEND 0x00000004 - #define SSH_FXF_CREAT 0x00000008 - #define SSH_FXF_TRUNC 0x00000010 - #define SSH_FXF_EXCL 0x00000020 - - These have the following meanings: - - SSH_FXF_READ - Open the file for reading. - - SSH_FXF_WRITE - Open the file for writing. If both this and SSH_FXF_READ are - specified, the file is opened for both reading and writing. - - SSH_FXF_APPEND - Force all writes to append data at the end of the file. - - SSH_FXF_CREAT - If this flag is specified, then a new file will be created if one - does not already exist (if O_TRUNC is specified, the new file will - be truncated to zero length if it previously exists). - - SSH_FXF_TRUNC - Forces an existing file with the same name to be truncated to zero - length when creating a file by specifying SSH_FXF_CREAT. - SSH_FXF_CREAT MUST also be specified if this flag is used. - - SSH_FXF_EXCL - Causes the request to fail if the named file already exists. - SSH_FXF_CREAT MUST also be specified if this flag is used. - - The `attrs' field specifies the initial attributes for the file. - Default values will be used for those attributes that are not - specified. See Section ``File Attributes'' for more information. - - Regardless the server operating system, the file will always be - opened in "binary" mode (i.e., no translations between different - character sets and newline encodings). - - The response to this message will be either SSH_FXP_HANDLE (if the - operation is successful) or SSH_FXP_STATUS (if the operation fails). - - - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 12] - -Internet-Draft SSH File Transfer Protocol October 2001 - - - A file is closed by using the SSH_FXP_CLOSE request. Its data field - has the following format: - - uint32 id - string handle - - where `id' is the request identifier, and `handle' is a handle - previously returned in the response to SSH_FXP_OPEN or - SSH_FXP_OPENDIR. The handle becomes invalid immediately after this - request has been sent. - - The response to this request will be a SSH_FXP_STATUS message. One - should note that on some server platforms even a close can fail. - This can happen e.g. if the server operating system caches writes, - and an error occurs while flushing cached writes during the close. - -6.4 Reading and Writing - - Once a file has been opened, it can be read using the SSH_FXP_READ - message, which has the following format: - - uint32 id - string handle - uint64 offset - uint32 len - - where `id' is the request identifier, `handle' is an open file handle - returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) relative - to the beginning of the file from where to start reading, and `len' - is the maximum number of bytes to read. - - In response to this request, the server will read as many bytes as it - can from the file (up to `len'), and return them in a SSH_FXP_DATA - message. If an error occurs or EOF is encountered before reading any - data, the server will respond with SSH_FXP_STATUS. For normal disk - files, it is guaranteed that this will read the specified number of - bytes, or up to end of file. For e.g. device files this may return - fewer bytes than requested. - - Writing to a file is achieved using the SSH_FXP_WRITE message, which - has the following format: - - uint32 id - string handle - uint64 offset - string data - - where `id' is a request identifier, `handle' is a file handle - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 13] - -Internet-Draft SSH File Transfer Protocol October 2001 - - - returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) from the - beginning of the file where to start writing, and `data' is the data - to be written. - - The write will extend the file if writing beyond the end of the file. - It is legal to write way beyond the end of the file; the semantics - are to write zeroes from the end of the file to the specified offset - and then the data. On most operating systems, such writes do not - allocate disk space but instead leave "holes" in the file. - - The server responds to a write request with a SSH_FXP_STATUS message. - -6.5 Removing and Renaming Files - - Files can be removed using the SSH_FXP_REMOVE message. It has the - following format: - - uint32 id - string filename - - where `id' is the request identifier and `filename' is the name of - the file to be removed. See Section ``File Names'' for more - information. This request cannot be used to remove directories. - - The server will respond to this request with a SSH_FXP_STATUS - message. - - Files (and directories) can be renamed using the SSH_FXP_RENAME - message. Its data is as follows: - - uint32 id - string oldpath - string newpath - - where `id' is the request identifier, `oldpath' is the name of an - existing file or directory, and `newpath' is the new name for the - file or directory. It is an error if there already exists a file - with the name specified by newpath. The server may also fail rename - requests in other situations, for example if `oldpath' and `newpath' - point to different file systems on the server. - - The server will respond to this request with a SSH_FXP_STATUS - message. - - - - - - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 14] - -Internet-Draft SSH File Transfer Protocol October 2001 - - -6.6 Creating and Deleting Directories - - New directories can be created using the SSH_FXP_MKDIR request. It - has the following format: - - uint32 id - string path - ATTRS attrs - - where `id' is the request identifier, `path' and `attrs' specifies - the modifications to be made to its attributes. See Section ``File - Names'' for more information on file names. Attributes are discussed - in more detail in Section ``File Attributes''. specifies the - directory to be created. An error will be returned if a file or - directory with the specified path already exists. The server will - respond to this request with a SSH_FXP_STATUS message. - - Directories can be removed using the SSH_FXP_RMDIR request, which - has the following format: - - uint32 id - string path - - where `id' is the request identifier, and `path' specifies the - directory to be removed. See Section ``File Names'' for more - information on file names. An error will be returned if no directory - with the specified path exists, or if the specified directory is not - empty, or if the path specified a file system object other than a - directory. The server responds to this request with a SSH_FXP_STATUS - message. - -6.7 Scanning Directories - - The files in a directory can be listed using the SSH_FXP_OPENDIR and - SSH_FXP_READDIR requests. Each SSH_FXP_READDIR request returns one - or more file names with full file attributes for each file. The - client should call SSH_FXP_READDIR repeatedly until it has found the - file it is looking for or until the server responds with a - SSH_FXP_STATUS message indicating an error (normally SSH_FX_EOF if - there are no more files in the directory). The client should then - close the handle using the SSH_FXP_CLOSE request. - - - - - - - - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 15] - -Internet-Draft SSH File Transfer Protocol October 2001 - - - The SSH_FXP_OPENDIR opens a directory for reading. It has the - following format: - - uint32 id - string path - - where `id' is the request identifier and `path' is the path name of - the directory to be listed (without any trailing slash). See Section - ``File Names'' for more information on file names. This will return - an error if the path does not specify a directory or if the directory - is not readable. The server will respond to this request with either - a SSH_FXP_HANDLE or a SSH_FXP_STATUS message. - - Once the directory has been successfully opened, files (and - directories) contained in it can be listed using SSH_FXP_READDIR - requests. These are of the format - - uint32 id - string handle - - where `id' is the request identifier, and `handle' is a handle - returned by SSH_FXP_OPENDIR. (It is a protocol error to attempt to - use an ordinary file handle returned by SSH_FXP_OPEN.) - - The server responds to this request with either a SSH_FXP_NAME or a - SSH_FXP_STATUS message. One or more names may be returned at a time. - Full status information is returned for each name in order to speed - up typical directory listings. - - When the client no longer wishes to read more names from the - directory, it SHOULD call SSH_FXP_CLOSE for the handle. The handle - should be closed regardless of whether an error has occurred or not. - -6.8 Retrieving File Attributes - - Very often, file attributes are automatically returned by - SSH_FXP_READDIR. However, sometimes there is need to specifically - retrieve the attributes for a named file. This can be done using the - SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests. - - SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT - follows symbolic links on the server, whereas SSH_FXP_LSTAT does not - follow symbolic links. Both have the same format: - - uint32 id - string path - - where `id' is the request identifier, and `path' specifies the file - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 16] - -Internet-Draft SSH File Transfer Protocol October 2001 - - - system object for which status is to be returned. The server - responds to this request with either SSH_FXP_ATTRS or SSH_FXP_STATUS. - - SSH_FXP_FSTAT differs from the others in that it returns status - information for an open file (identified by the file handle). Its - format is as follows: - - uint32 id - string handle - - where `id' is the request identifier and `handle' is a file handle - returned by SSH_FXP_OPEN. The server responds to this request with - SSH_FXP_ATTRS or SSH_FXP_STATUS. - -6.9 Setting File Attributes - - File attributes may be modified using the SSH_FXP_SETSTAT and - SSH_FXP_FSETSTAT requests. These requests are used for operations - such as changing the ownership, permissions or access times, as well - as for truncating a file. - - The SSH_FXP_SETSTAT request is of the following format: - - uint32 id - string path - ATTRS attrs - - where `id' is the request identifier, `path' specifies the file - system object (e.g. file or directory) whose attributes are to be - modified, and `attrs' specifies the modifications to be made to its - attributes. Attributes are discussed in more detail in Section - ``File Attributes''. - - An error will be returned if the specified file system object does - not exist or the user does not have sufficient rights to modify the - specified attributes. The server responds to this request with a - SSH_FXP_STATUS message. - - The SSH_FXP_FSETSTAT request modifies the attributes of a file which - is already open. It has the following format: - - uint32 id - string handle - ATTRS attrs - - where `id' is the request identifier, `handle' (MUST be returned by - SSH_FXP_OPEN) identifies the file whose attributes are to be - modified, and `attrs' specifies the modifications to be made to its - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 17] - -Internet-Draft SSH File Transfer Protocol October 2001 - - - attributes. Attributes are discussed in more detail in Section - ``File Attributes''. The server will respond to this request with - SSH_FXP_STATUS. - -6.10 Dealing with Symbolic links - - The SSH_FXP_READLINK request may be used to read the target of a - symbolic link. It would have a data part as follows: - - uint32 id - string path - - where `id' is the request identifier and `path' specifies the path - name of the symlink to be read. - - The server will respond with a SSH_FXP_NAME packet containing only - one name and a dummy attributes value. The name in the returned - packet contains the target of the link. If an error occurs, the - server may respond with SSH_FXP_STATUS. - - The SSH_FXP_SYMLINK request will create a symbolic link on the - server. It is of the following format - - uint32 id - string linkpath - string targetpath - - where `id' is the request identifier, `linkpath' specifies the path - name of the symlink to be created and `targetpath' specifies the - target of the symlink. The server shall respond with a - SSH_FXP_STATUS indicating either success (SSH_FX_OK) or an error - condition. - -6.11 Canonicalizing the Server-Side Path Name - - The SSH_FXP_REALPATH request can be used to have the server - canonicalize any given path name to an absolute path. This is useful - for converting path names containing ".." components or relative - pathnames without a leading slash into absolute paths. The format of - the request is as follows: - - uint32 id - string path - - where `id' is the request identifier and `path' specifies the path - name to be canonicalized. The server will respond with a - SSH_FXP_NAME packet containing only one name and a dummy attributes - value. The name is the returned packet will be in canonical form. - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 18] - -Internet-Draft SSH File Transfer Protocol October 2001 - - - If an error occurs, the server may also respond with SSH_FXP_STATUS. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 19] - -Internet-Draft SSH File Transfer Protocol October 2001 - - -7. Responses from the Server to the Client - - The server responds to the client using one of a few response - packets. All requests can return a SSH_FXP_STATUS response upon - failure. When the operation is successful, any of the responses may - be returned (depending on the operation). If no data needs to be - returned to the client, the SSH_FXP_STATUS response with SSH_FX_OK - status is appropriate. Otherwise, the SSH_FXP_HANDLE message is used - to return a file handle (for SSH_FXP_OPEN and SSH_FXP_OPENDIR - requests), SSH_FXP_DATA is used to return data from SSH_FXP_READ, - SSH_FXP_NAME is used to return one or more file names from a - SSH_FXP_READDIR or SSH_FXP_REALPATH request, and SSH_FXP_ATTRS is - used to return file attributes from SSH_FXP_STAT, SSH_FXP_LSTAT, and - SSH_FXP_FSTAT requests. - - Exactly one response will be returned for each request. Each - response packet contains a request identifier which can be used to - match each response with the corresponding request. Note that it is - legal to have several requests outstanding simultaneously, and the - server is allowed to send responses to them in a different order from - the order in which the requests were sent (the result of their - execution, however, is guaranteed to be as if they had been processed - one at a time in the order in which the requests were sent). - - Response packets are of the same general format as request packets. - Each response packet begins with the request identifier. - - The format of the data portion of the SSH_FXP_STATUS response is as - follows: - - uint32 id - uint32 error/status code - string error message (ISO-10646 UTF-8 [RFC-2279]) - string language tag (as defined in [RFC-1766]) - - where `id' is the request identifier, and `error/status code' - indicates the result of the requested operation. The value SSH_FX_OK - indicates success, and all other values indicate failure. - - - - - - - - - - - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 20] - -Internet-Draft SSH File Transfer Protocol October 2001 - - - Currently, the following values are defined (other values may be - defined by future versions of this protocol): - - #define SSH_FX_OK 0 - #define SSH_FX_EOF 1 - #define SSH_FX_NO_SUCH_FILE 2 - #define SSH_FX_PERMISSION_DENIED 3 - #define SSH_FX_FAILURE 4 - #define SSH_FX_BAD_MESSAGE 5 - #define SSH_FX_NO_CONNECTION 6 - #define SSH_FX_CONNECTION_LOST 7 - #define SSH_FX_OP_UNSUPPORTED 8 - - SSH_FX_OK - Indicates successful completion of the operation. - - SSH_FX_EOF - indicates end-of-file condition; for SSH_FX_READ it means that no - more data is available in the file, and for SSH_FX_READDIR it - indicates that no more files are contained in the directory. - - SSH_FX_NO_SUCH_FILE - is returned when a reference is made to a file which should exist - but doesn't. - - SSH_FX_PERMISSION_DENIED - is returned when the authenticated user does not have sufficient - permissions to perform the operation. - - SSH_FX_FAILURE - is a generic catch-all error message; it should be returned if an - error occurs for which there is no more specific error code - defined. - - SSH_FX_BAD_MESSAGE - may be returned if a badly formatted packet or protocol - incompatibility is detected. - - SSH_FX_NO_CONNECTION - is a pseudo-error which indicates that the client has no - connection to the server (it can only be generated locally by the - client, and MUST NOT be returned by servers). - - SSH_FX_CONNECTION_LOST - is a pseudo-error which indicates that the connection to the - server has been lost (it can only be generated locally by the - client, and MUST NOT be returned by servers). - - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 21] - -Internet-Draft SSH File Transfer Protocol October 2001 - - - SSH_FX_OP_UNSUPPORTED - indicates that an attempt was made to perform an operation which - is not supported for the server (it may be generated locally by - the client if e.g. the version number exchange indicates that a - required feature is not supported by the server, or it may be - returned by the server if the server does not implement an - operation). - - The SSH_FXP_HANDLE response has the following format: - - uint32 id - string handle - - where `id' is the request identifier, and `handle' is an arbitrary - string that identifies an open file or directory on the server. The - handle is opaque to the client; the client MUST NOT attempt to - interpret or modify it in any way. The length of the handle string - MUST NOT exceed 256 data bytes. - - The SSH_FXP_DATA response has the following format: - - uint32 id - string data - - where `id' is the request identifier, and `data' is an arbitrary byte - string containing the requested data. The data string may be at most - the number of bytes requested in a SSH_FXP_READ request, but may also - be shorter if end of file is reached or if the read is from something - other than a regular file. - - The SSH_FXP_NAME response has the following format: - - uint32 id - uint32 count - repeats count times: - string filename - string longname - ATTRS attrs - - where `id' is the request identifier, `count' is the number of names - returned in this response, and the remaining fields repeat `count' - times (so that all three fields are first included for the first - file, then for the second file, etc). In the repeated part, - `filename' is a file name being returned (for SSH_FXP_READDIR, it - will be a relative name within the directory, without any path - components; for SSH_FXP_REALPATH it will be an absolute path name), - `longname' is an expanded format for the file name, similar to what - is returned by "ls -l" on Unix systems, and `attrs' is the attributes - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 22] - -Internet-Draft SSH File Transfer Protocol October 2001 - - - of the file as described in Section ``File Attributes''. - - The format of the `longname' field is unspecified by this protocol. - It MUST be suitable for use in the output of a directory listing - command (in fact, the recommended operation for a directory listing - command is to simply display this data). However, clients SHOULD NOT - attempt to parse the longname field for file attributes; they SHOULD - use the attrs field instead. - - The recommended format for the longname field is as follows: - - -rwxr-xr-x 1 mjos staff 348911 Mar 25 14:29 t-filexfer - 1234567890 123 12345678 12345678 12345678 123456789012 - - Here, the first line is sample output, and the second field indicates - widths of the various fields. Fields are separated by spaces. The - first field lists file permissions for user, group, and others; the - second field is link count; the third field is the name of the user - who owns the file; the fourth field is the name of the group that - owns the file; the fifth field is the size of the file in bytes; the - sixth field (which actually may contain spaces, but is fixed to 12 - characters) is the file modification time, and the seventh field is - the file name. Each field is specified to be a minimum of certain - number of character positions (indicated by the second line above), - but may also be longer if the data does not fit in the specified - length. - - The SSH_FXP_ATTRS response has the following format: - - uint32 id - ATTRS attrs - - where `id' is the request identifier, and `attrs' is the returned - file attributes as described in Section ``File Attributes''. - - - - - - - - - - - - - - - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 23] - -Internet-Draft SSH File Transfer Protocol October 2001 - - -8. Vendor-Specific Extensions - - The SSH_FXP_EXTENDED request provides a generic extension mechanism - for adding vendor-specific commands. The request has the following - format: - - uint32 id - string extended-request - ... any request-specific data ... - - where `id' is the request identifier, and `extended-request' is a - string of the format "name@domain", where domain is an internet - domain name of the vendor defining the request. The rest of the - request is completely vendor-specific, and servers should only - attempt to interpret it if they recognize the `extended-request' - name. - - The server may respond to such requests using any of the response - packets defined in Section ``Responses from the Server to the - Client''. Additionally, the server may also respond with a - SSH_FXP_EXTENDED_REPLY packet, as defined below. If the server does - not recognize the `extended-request' name, then the server MUST - respond with SSH_FXP_STATUS with error/status set to - SSH_FX_OP_UNSUPPORTED. - - The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary - extension-specific data from the server to the client. It is of the - following format: - - uint32 id - ... any request-specific data ... - - - - - - - - - - - - - - - - - - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 24] - -Internet-Draft SSH File Transfer Protocol October 2001 - - -9. Security Considerations - - This protocol assumes that it is run over a secure channel and that - the endpoints of the channel have been authenticated. Thus, this - protocol assumes that it is externally protected from network-level - attacks. - - This protocol provides file system access to arbitrary files on the - server (only constrained by the server implementation). It is the - responsibility of the server implementation to enforce any access - controls that may be required to limit the access allowed for any - particular user (the user being authenticated externally to this - protocol, typically using the SSH User Authentication Protocol [6]. - - Care must be taken in the server implementation to check the validity - of received file handle strings. The server should not rely on them - directly; it MUST check the validity of each handle before relying on - it. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 25] - -Internet-Draft SSH File Transfer Protocol October 2001 - - -10. Changes from previous protocol versions - - The SSH File Transfer Protocol has changed over time, before it's - standardization. The following is a description of the incompatible - changes between different versions. - -10.1 Changes between versions 3 and 2 - - o The SSH_FXP_READLINK and SSH_FXP_SYMLINK messages were added. - - o The SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY messages were - added. - - o The SSH_FXP_STATUS message was changed to include fields `error - message' and `language tag'. - - -10.2 Changes between versions 2 and 1 - - o The SSH_FXP_RENAME message was added. - - -10.3 Changes between versions 1 and 0 - - o Implementation changes, no actual protocol changes. - - - - - - - - - - - - - - - - - - - - - - - - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 26] - -Internet-Draft SSH File Transfer Protocol October 2001 - - -11. Trademark Issues - - "ssh" is a registered trademark of SSH Communications Security Corp - in the United States and/or other countries. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 27] - -Internet-Draft SSH File Transfer Protocol October 2001 - - -References - - [1] Dierks, T., Allen, C., Treese, W., Karlton, P., Freier, A. and - P. Kocher, "The TLS Protocol Version 1.0", RFC 2246, January - 1999. - - [2] Institute of Electrical and Electronics Engineers, "Information - Technology - Portable Operating System Interface (POSIX) - Part - 1: System Application Program Interface (API) [C Language]", - IEEE Standard 1003.2, 1996. - - [3] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S. - Lehtinen, "SSH Protocol Architecture", draft-ietf-secsh- - architecture-09 (work in progress), July 2001. - - [4] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S. - Lehtinen, "SSH Protocol Transport Protocol", draft-ietf-secsh- - architecture-09 (work in progress), July 2001. - - [5] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S. - Lehtinen, "SSH Connection Protocol", draft-ietf-secsh-connect-11 - (work in progress), July 2001. - - [6] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S. - Lehtinen, "SSH Authentication Protocol", draft-ietf-secsh- - userauth-11 (work in progress), July 2001. - - -Authors' Addresses - - Tatu Ylonen - SSH Communications Security Corp - Fredrikinkatu 42 - HELSINKI FIN-00100 - Finland - - EMail: [email protected] - - - Sami Lehtinen - SSH Communications Security Corp - Fredrikinkatu 42 - HELSINKI FIN-00100 - Finland - - EMail: [email protected] - - - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 28] - -Internet-Draft SSH File Transfer Protocol October 2001 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2001). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assigns. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS 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. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - - - - - - - - - - - -Ylonen & Lehtinen Expires April 1, 2002 [Page 29] - - - diff --git a/lib/ssh/doc/standard/draft-ietf-secsh-filexfer-03.2.ps b/lib/ssh/doc/standard/draft-ietf-secsh-filexfer-03.2.ps deleted file mode 100644 index 6a40cd6067..0000000000 --- a/lib/ssh/doc/standard/draft-ietf-secsh-filexfer-03.2.ps +++ /dev/null @@ -1,3511 +0,0 @@ -%!PS-Adobe-3.0 -%%BoundingBox: 75 0 595 747 -%%Title: Enscript Output -%%For: Magnus Thoang -%%Creator: GNU enscript 1.6.1 -%%CreationDate: Wed Nov 12 12:18:50 2003 -%%Orientation: Portrait -%%Pages: 18 0 -%%DocumentMedia: A4 595 842 0 () () -%%DocumentNeededResources: (atend) -%%EndComments -%%BeginProlog -%%BeginProcSet: PStoPS 1 15 -userdict begin -[/showpage/erasepage/copypage]{dup where{pop dup load - type/operatortype eq{1 array cvx dup 0 3 index cvx put - bind def}{pop}ifelse}{pop}ifelse}forall -[/letter/legal/executivepage/a4/a4small/b5/com10envelope - /monarchenvelope/c5envelope/dlenvelope/lettersmall/note - /folio/quarto/a5]{dup where{dup wcheck{exch{}put} - {pop{}def}ifelse}{pop}ifelse}forall -/setpagedevice {pop}bind 1 index where{dup wcheck{3 1 roll put} - {pop def}ifelse}{def}ifelse -/PStoPSmatrix matrix currentmatrix def -/PStoPSxform matrix def/PStoPSclip{clippath}def -/defaultmatrix{PStoPSmatrix exch PStoPSxform exch concatmatrix}bind def -/initmatrix{matrix defaultmatrix setmatrix}bind def -/initclip[{matrix currentmatrix PStoPSmatrix setmatrix - [{currentpoint}stopped{$error/newerror false put{newpath}} - {/newpath cvx 3 1 roll/moveto cvx 4 array astore cvx}ifelse] - {[/newpath cvx{/moveto cvx}{/lineto cvx} - {/curveto cvx}{/closepath cvx}pathforall]cvx exch pop} - stopped{$error/errorname get/invalidaccess eq{cleartomark - $error/newerror false put cvx exec}{stop}ifelse}if}bind aload pop - /initclip dup load dup type dup/operatortype eq{pop exch pop} - {dup/arraytype eq exch/packedarraytype eq or - {dup xcheck{exch pop aload pop}{pop cvx}ifelse} - {pop cvx}ifelse}ifelse - {newpath PStoPSclip clip newpath exec setmatrix} bind aload pop]cvx def -/initgraphics{initmatrix newpath initclip 1 setlinewidth - 0 setlinecap 0 setlinejoin []0 setdash 0 setgray - 10 setmiterlimit}bind def -end -%%EndProcSet -%%BeginResource: procset Enscript-Prolog 1.6 1 -% -% Procedures. -% - -/_S { % save current state - /_s save def -} def -/_R { % restore from saved state - _s restore -} def - -/S { % showpage protecting gstate - gsave - showpage - grestore -} bind def - -/MF { % fontname newfontname -> - make a new encoded font - /newfontname exch def - /fontname exch def - - /fontdict fontname findfont def - /newfont fontdict maxlength dict def - - fontdict { - exch - dup /FID eq { - % skip FID pair - pop pop - } { - % copy to the new font dictionary - exch newfont 3 1 roll put - } ifelse - } forall - - newfont /FontName newfontname put - - % insert only valid encoding vectors - encoding_vector length 256 eq { - newfont /Encoding encoding_vector put - } if - - newfontname newfont definefont pop -} def - -/SF { % fontname width height -> - set a new font - /height exch def - /width exch def - - findfont - [width 0 0 height 0 0] makefont setfont -} def - -/SUF { % fontname width height -> - set a new user font - /height exch def - /width exch def - - /F-gs-user-font MF - /F-gs-user-font width height SF -} def - -/M {moveto} bind def -/s {show} bind def - -/Box { % x y w h -> - define box path - /d_h exch def /d_w exch def /d_y exch def /d_x exch def - d_x d_y moveto - d_w 0 rlineto - 0 d_h rlineto - d_w neg 0 rlineto - closepath -} def - -/bgs { % x y height blskip gray str -> - show string with bg color - /str exch def - /gray exch def - /blskip exch def - /height exch def - /y exch def - /x exch def - - gsave - x y blskip sub str stringwidth pop height Box - gray setgray - fill - grestore - x y M str s -} def - -% Highlight bars. -/highlight_bars { % nlines lineheight output_y_margin gray -> - - gsave - setgray - /ymarg exch def - /lineheight exch def - /nlines exch def - - % This 2 is just a magic number to sync highlight lines to text. - 0 d_header_y ymarg sub 2 sub translate - - /cw d_output_w cols div def - /nrows d_output_h ymarg 2 mul sub lineheight div cvi def - - % for each column - 0 1 cols 1 sub { - cw mul /xp exch def - - % for each rows - 0 1 nrows 1 sub { - /rn exch def - rn lineheight mul neg /yp exch def - rn nlines idiv 2 mod 0 eq { - % Draw highlight bar. 4 is just a magic indentation. - xp 4 add yp cw 8 sub lineheight neg Box fill - } if - } for - } for - - grestore -} def - -% Line highlight bar. -/line_highlight { % x y width height gray -> - - gsave - /gray exch def - Box gray setgray fill - grestore -} def - -% Column separator lines. -/column_lines { - gsave - .1 setlinewidth - 0 d_footer_h translate - /cw d_output_w cols div def - 1 1 cols 1 sub { - cw mul 0 moveto - 0 d_output_h rlineto stroke - } for - grestore -} def - -% Column borders. -/column_borders { - gsave - .1 setlinewidth - 0 d_footer_h moveto - 0 d_output_h rlineto - d_output_w 0 rlineto - 0 d_output_h neg rlineto - closepath stroke - grestore -} def - -% Do the actual underlay drawing -/draw_underlay { - ul_style 0 eq { - ul_str true charpath stroke - } { - ul_str show - } ifelse -} def - -% Underlay -/underlay { % - -> - - gsave - 0 d_page_h translate - d_page_h neg d_page_w atan rotate - - ul_gray setgray - ul_font setfont - /dw d_page_h dup mul d_page_w dup mul add sqrt def - ul_str stringwidth pop dw exch sub 2 div ul_h_ptsize -2 div moveto - draw_underlay - grestore -} def - -/user_underlay { % - -> - - gsave - ul_x ul_y translate - ul_angle rotate - ul_gray setgray - ul_font setfont - 0 0 ul_h_ptsize 2 div sub moveto - draw_underlay - grestore -} def - -% Page prefeed -/page_prefeed { % bool -> - - statusdict /prefeed known { - statusdict exch /prefeed exch put - } { - pop - } ifelse -} def - -% Wrapped line markers -/wrapped_line_mark { % x y charwith charheight type -> - - /type exch def - /h exch def - /w exch def - /y exch def - /x exch def - - type 2 eq { - % Black boxes (like TeX does) - gsave - 0 setlinewidth - x w 4 div add y M - 0 h rlineto w 2 div 0 rlineto 0 h neg rlineto - closepath fill - grestore - } { - type 3 eq { - % Small arrows - gsave - .2 setlinewidth - x w 2 div add y h 2 div add M - w 4 div 0 rlineto - x w 4 div add y lineto stroke - - x w 4 div add w 8 div add y h 4 div add M - x w 4 div add y lineto - w 4 div h 8 div rlineto stroke - grestore - } { - % do nothing - } ifelse - } ifelse -} def - -% EPSF import. - -/BeginEPSF { - /b4_Inc_state save def % Save state for cleanup - /dict_count countdictstack def % Count objects on dict stack - /op_count count 1 sub def % Count objects on operand stack - userdict begin - /showpage { } def - 0 setgray 0 setlinecap - 1 setlinewidth 0 setlinejoin - 10 setmiterlimit [ ] 0 setdash newpath - /languagelevel where { - pop languagelevel - 1 ne { - false setstrokeadjust false setoverprint - } if - } if -} bind def - -/EndEPSF { - count op_count sub { pos } repeat % Clean up stacks - countdictstack dict_count sub { end } repeat - b4_Inc_state restore -} bind def - -% Check PostScript language level. -/languagelevel where { - pop /gs_languagelevel languagelevel def -} { - /gs_languagelevel 1 def -} ifelse -%%EndResource -%%BeginResource: procset Enscript-Encoding-88591 1.6 1 -/encoding_vector [ -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/space /exclam /quotedbl /numbersign -/dollar /percent /ampersand /quoteright -/parenleft /parenright /asterisk /plus -/comma /hyphen /period /slash -/zero /one /two /three -/four /five /six /seven -/eight /nine /colon /semicolon -/less /equal /greater /question -/at /A /B /C -/D /E /F /G -/H /I /J /K -/L /M /N /O -/P /Q /R /S -/T /U /V /W -/X /Y /Z /bracketleft -/backslash /bracketright /asciicircum /underscore -/quoteleft /a /b /c -/d /e /f /g -/h /i /j /k -/l /m /n /o -/p /q /r /s -/t /u /v /w -/x /y /z /braceleft -/bar /braceright /tilde /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/space /exclamdown /cent /sterling -/currency /yen /brokenbar /section -/dieresis /copyright /ordfeminine /guillemotleft -/logicalnot /hyphen /registered /macron -/degree /plusminus /twosuperior /threesuperior -/acute /mu /paragraph /bullet -/cedilla /onesuperior /ordmasculine /guillemotright -/onequarter /onehalf /threequarters /questiondown -/Agrave /Aacute /Acircumflex /Atilde -/Adieresis /Aring /AE /Ccedilla -/Egrave /Eacute /Ecircumflex /Edieresis -/Igrave /Iacute /Icircumflex /Idieresis -/Eth /Ntilde /Ograve /Oacute -/Ocircumflex /Otilde /Odieresis /multiply -/Oslash /Ugrave /Uacute /Ucircumflex -/Udieresis /Yacute /Thorn /germandbls -/agrave /aacute /acircumflex /atilde -/adieresis /aring /ae /ccedilla -/egrave /eacute /ecircumflex /edieresis -/igrave /iacute /icircumflex /idieresis -/eth /ntilde /ograve /oacute -/ocircumflex /otilde /odieresis /divide -/oslash /ugrave /uacute /ucircumflex -/udieresis /yacute /thorn /ydieresis -] def -%%EndResource -%%EndProlog -%%BeginSetup -%%IncludeResource: font Courier-Bold -%%IncludeResource: font Courier -/HFpt_w 10 def -/HFpt_h 10 def -/Courier-Bold /HF-gs-font MF -/HF /HF-gs-font findfont [HFpt_w 0 0 HFpt_h 0 0] makefont def -/Courier /F-gs-font MF -/F-gs-font 10 10 SF -/#copies 1 def -/d_page_w 520 def -/d_page_h 747 def -/d_header_x 0 def -/d_header_y 747 def -/d_header_w 520 def -/d_header_h 0 def -/d_footer_x 0 def -/d_footer_y 0 def -/d_footer_w 520 def -/d_footer_h 0 def -/d_output_w 520 def -/d_output_h 747 def -/cols 1 def -userdict/PStoPSxform PStoPSmatrix matrix currentmatrix - matrix invertmatrix matrix concatmatrix - matrix invertmatrix put -%%EndSetup -%%Page: (0,1) 1 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 1 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 701 M -(Secure Shell Working Group J. Galbraith) s -5 690 M -(Internet-Draft VanDyke Software) s -5 679 M -(Expires: April 16, 2003 T. Ylonen) s -5 668 M -( S. Lehtinen) s -5 657 M -( SSH Communications Security Corp) s -5 646 M -( October 16, 2002) s -5 613 M -( SSH File Transfer Protocol) s -5 602 M -( draft-ietf-secsh-filexfer-03.txt) s -5 580 M -(Status of this Memo) s -5 558 M -( This document is an Internet-Draft and is in full conformance with) s -5 547 M -( all provisions of Section 10 of RFC2026.) s -5 525 M -( Internet-Drafts are working documents of the Internet Engineering) s -5 514 M -( Task Force \(IETF\), its areas, and its working groups. Note that) s -5 503 M -( other groups may also distribute working documents as Internet-) s -5 492 M -( Drafts.) s -5 470 M -( Internet-Drafts are draft documents valid for a maximum of six months) s -5 459 M -( and may be updated, replaced, or obsoleted by other documents at any) s -5 448 M -( time. It is inappropriate to use Internet-Drafts as reference) s -5 437 M -( material or to cite them other than as "work in progress.") s -5 415 M -( The list of current Internet-Drafts can be accessed at http://) s -5 404 M -( www.ietf.org/ietf/1id-abstracts.txt.) s -5 382 M -( The list of Internet-Draft Shadow Directories can be accessed at) s -5 371 M -( http://www.ietf.org/shadow.html.) s -5 349 M -( This Internet-Draft will expire on April 16, 2003.) s -5 327 M -(Copyright Notice) s -5 305 M -( Copyright \(C\) The Internet Society \(2002\). All Rights Reserved.) s -5 283 M -(Abstract) s -5 261 M -( The SSH File Transfer Protocol provides secure file transfer) s -5 250 M -( functionality over any reliable data stream. It is the standard file) s -5 239 M -( transfer protocol for use with the SSH2 protocol. This document) s -5 228 M -( describes the file transfer protocol and its interface to the SSH2) s -5 217 M -( protocol suite.) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 1]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 2 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -(Table of Contents) s -5 668 M -( 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 3) s -5 657 M -( 2. Use with the SSH Connection Protocol . . . . . . . . . . . 4) s -5 646 M -( 3. General Packet Format . . . . . . . . . . . . . . . . . . 5) s -5 635 M -( 4. Protocol Initialization . . . . . . . . . . . . . . . . . 7) s -5 624 M -( 4.1 Client Initialization . . . . . . . . . . . . . . . . . . 7) s -5 613 M -( 4.2 Server Initialization . . . . . . . . . . . . . . . . . . 7) s -5 602 M -( 4.3 Determining Server Newline Convention . . . . . . . . . . 8) s -5 591 M -( 5. File Attributes . . . . . . . . . . . . . . . . . . . . . 9) s -5 580 M -( 5.1 Flags . . . . . . . . . . . . . . . . . . . . . . . . . . 9) s -5 569 M -( 5.2 Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 10) s -5 558 M -( 5.3 Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 10) s -5 547 M -( 5.4 Owner and Group . . . . . . . . . . . . . . . . . . . . . 10) s -5 536 M -( 5.5 Permissions . . . . . . . . . . . . . . . . . . . . . . . 11) s -5 525 M -( 5.6 Times . . . . . . . . . . . . . . . . . . . . . . . . . . 11) s -5 514 M -( 5.7 ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 11) s -5 503 M -( 5.8 Extended attributes . . . . . . . . . . . . . . . . . . . 12) s -5 492 M -( 6. Requests From the Client to the Server . . . . . . . . . . 13) s -5 481 M -( 6.1 Request Synchronization and Reordering . . . . . . . . . . 13) s -5 470 M -( 6.2 File Names . . . . . . . . . . . . . . . . . . . . . . . . 14) s -5 459 M -( 6.3 Opening, Creating, and Closing Files . . . . . . . . . . . 14) s -5 448 M -( 6.4 Reading and Writing . . . . . . . . . . . . . . . . . . . 17) s -5 437 M -( 6.5 Removing and Renaming Files . . . . . . . . . . . . . . . 18) s -5 426 M -( 6.6 Creating and Deleting Directories . . . . . . . . . . . . 19) s -5 415 M -( 6.7 Scanning Directories . . . . . . . . . . . . . . . . . . . 19) s -5 404 M -( 6.8 Retrieving File Attributes . . . . . . . . . . . . . . . . 20) s -5 393 M -( 6.9 Setting File Attributes . . . . . . . . . . . . . . . . . 21) s -5 382 M -( 6.10 Dealing with Symbolic links . . . . . . . . . . . . . . . 22) s -5 371 M -( 6.11 Canonicalizing the Server-Side Path Name . . . . . . . . . 23) s -5 360 M -( 6.11.1 Best practice for dealing with paths . . . . . . . . . . . 23) s -5 349 M -( 7. Responses from the Server to the Client . . . . . . . . . 24) s -5 338 M -( 8. Vendor-Specific Extensions . . . . . . . . . . . . . . . . 28) s -5 327 M -( 9. Security Considerations . . . . . . . . . . . . . . . . . 29) s -5 316 M -( 10. Changes from previous protocol versions . . . . . . . . . 30) s -5 305 M -( 10.1 Changes between versions 4 and 3 . . . . . . . . . . . . . 30) s -5 294 M -( 10.2 Changes between versions 3 and 2 . . . . . . . . . . . . . 31) s -5 283 M -( 10.3 Changes between versions 2 and 1 . . . . . . . . . . . . . 31) s -5 272 M -( 10.4 Changes between versions 1 and 0 . . . . . . . . . . . . . 31) s -5 261 M -( 11. Trademark Issues . . . . . . . . . . . . . . . . . . . . . 32) s -5 250 M -( References . . . . . . . . . . . . . . . . . . . . . . . . 33) s -5 239 M -( Authors' Addresses . . . . . . . . . . . . . . . . . . . . 33) s -5 228 M -( Full Copyright Statement . . . . . . . . . . . . . . . . . 35) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 2]) s -_R -S -PStoPSsaved restore -%%Page: (2,3) 2 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 3 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -(1. Introduction) s -5 668 M -( This protocol provides secure file transfer \(and more generally file) s -5 657 M -( system access\) functionality over a reliable data stream, such as a) s -5 646 M -( channel in the SSH2 protocol [5].) s -5 624 M -( This protocol is designed so that it could be used to implement a) s -5 613 M -( secure remote file system service, as well as a secure file transfer) s -5 602 M -( service.) s -5 580 M -( This protocol assumes that it runs over a secure channel, and that) s -5 569 M -( the server has already authenticated the user at the client end, and) s -5 558 M -( that the identity of the client user is externally available to the) s -5 547 M -( server implementation.) s -5 525 M -( In general, this protocol follows a simple request-response model.) s -5 514 M -( Each request and response contains a sequence number and multiple) s -5 503 M -( requests may be pending simultaneously. There are a relatively large) s -5 492 M -( number of different request messages, but a small number of possible) s -5 481 M -( response messages. Each request has one or more response messages) s -5 470 M -( that may be returned in result \(e.g., a read either returns data or) s -5 459 M -( reports error status\).) s -5 437 M -( The packet format descriptions in this specification follow the) s -5 426 M -( notation presented in the secsh architecture draft. [5]) s -5 404 M -( Even though this protocol is described in the context of the SSH2) s -5 393 M -( protocol, this protocol is general and independent of the rest of the) s -5 382 M -( SSH2 protocol suite. It could be used in a number of different) s -5 371 M -( applications, such as secure file transfer over TLS RFC 2246 [1] and) s -5 360 M -( transfer of management information in VPN applications.) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 3]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 4 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -(2. Use with the SSH Connection Protocol) s -5 668 M -( When used with the SSH2 Protocol suite, this protocol is intended to) s -5 657 M -( be used from the SSH Connection Protocol [7] as a subsystem, as) s -5 646 M -( described in section ``Starting a Shell or a Command''. The) s -5 635 M -( subsystem name used with this protocol is "sftp".) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 4]) s -_R -S -PStoPSsaved restore -%%Page: (4,5) 3 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 5 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -(3. General Packet Format) s -5 668 M -( All packets transmitted over the secure connection are of the) s -5 657 M -( following format:) s -5 635 M -( uint32 length) s -5 624 M -( byte type) s -5 613 M -( byte[length - 1] data payload) s -5 591 M -( That is, they are just data preceded by 32-bit length and 8-bit type) s -5 580 M -( fields. The `length' is the length of the data area, and does not) s -5 569 M -( include the `length' field itself. The format and interpretation of) s -5 558 M -( the data area depends on the packet type.) s -5 536 M -( All packet descriptions below only specify the packet type and the) s -5 525 M -( data that goes into the data field. Thus, they should be prefixed by) s -5 514 M -( the `length' and `type' fields.) s -5 492 M -( The maximum size of a packet is in practice determined by the client) s -5 481 M -( \(the maximum size of read or write requests that it sends, plus a few) s -5 470 M -( bytes of packet overhead\). All servers SHOULD support packets of at) s -5 459 M -( least 34000 bytes \(where the packet size refers to the full length,) s -5 448 M -( including the header above\). This should allow for reads and writes) s -5 437 M -( of at most 32768 bytes.) s -5 415 M -( There is no limit on the number of outstanding \(non-acknowledged\)) s -5 404 M -( requests that the client may send to the server. In practice this is) s -5 393 M -( limited by the buffering available on the data stream and the queuing) s -5 382 M -( performed by the server. If the server's queues are full, it should) s -5 371 M -( not read any more data from the stream, and flow control will prevent) s -5 360 M -( the client from sending more requests. Note, however, that while) s -5 349 M -( there is no restriction on the protocol level, the client's API may) s -5 338 M -( provide a limit in order to prevent infinite queuing of outgoing) s -5 327 M -( requests at the client.) s -5 305 M -( The following values are defined for packet types.) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 5]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 6 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -( #define SSH_FXP_INIT 1) s -5 679 M -( #define SSH_FXP_VERSION 2) s -5 668 M -( #define SSH_FXP_OPEN 3) s -5 657 M -( #define SSH_FXP_CLOSE 4) s -5 646 M -( #define SSH_FXP_READ 5) s -5 635 M -( #define SSH_FXP_WRITE 6) s -5 624 M -( #define SSH_FXP_LSTAT 7) s -5 613 M -( #define SSH_FXP_FSTAT 8) s -5 602 M -( #define SSH_FXP_SETSTAT 9) s -5 591 M -( #define SSH_FXP_FSETSTAT 10) s -5 580 M -( #define SSH_FXP_OPENDIR 11) s -5 569 M -( #define SSH_FXP_READDIR 12) s -5 558 M -( #define SSH_FXP_REMOVE 13) s -5 547 M -( #define SSH_FXP_MKDIR 14) s -5 536 M -( #define SSH_FXP_RMDIR 15) s -5 525 M -( #define SSH_FXP_REALPATH 16) s -5 514 M -( #define SSH_FXP_STAT 17) s -5 503 M -( #define SSH_FXP_RENAME 18) s -5 492 M -( #define SSH_FXP_READLINK 19) s -5 481 M -( #define SSH_FXP_SYMLINK 20) s -5 459 M -( #define SSH_FXP_STATUS 101) s -5 448 M -( #define SSH_FXP_HANDLE 102) s -5 437 M -( #define SSH_FXP_DATA 103) s -5 426 M -( #define SSH_FXP_NAME 104) s -5 415 M -( #define SSH_FXP_ATTRS 105) s -5 393 M -( #define SSH_FXP_EXTENDED 200) s -5 382 M -( #define SSH_FXP_EXTENDED_REPLY 201) s -5 360 M -( RESERVED_FOR_EXTENSIONS 210-255) s -5 338 M -( Additional packet types should only be defined if the protocol) s -5 327 M -( version number \(see Section ``Protocol Initialization''\) is) s -5 316 M -( incremented, and their use MUST be negotiated using the version) s -5 305 M -( number. However, the SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY) s -5 294 M -( packets can be used to implement vendor-specific extensions. See) s -5 283 M -( Section ``Vendor-Specific-Extensions'' for more details.) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 6]) s -_R -S -PStoPSsaved restore -%%Page: (6,7) 4 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 7 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -(4. Protocol Initialization) s -5 668 M -( When the file transfer protocol starts, the client first sends a) s -5 657 M -( SSH_FXP_INIT \(including its version number\) packet to the server.) s -5 646 M -( The server responds with a SSH_FXP_VERSION packet, supplying the) s -5 635 M -( lowest of its own and the client's version number. Both parties) s -5 624 M -( should from then on adhere to particular version of the protocol.) s -5 602 M -( The version number of the protocol specified in this document is 4.) s -5 591 M -( The version number should be incremented for each incompatible) s -5 580 M -( revision of this protocol.) s -5 558 M -(4.1 Client Initialization) s -5 536 M -( The SSH_FXP_INIT packet \(from client to server\) has the following) s -5 525 M -( data:) s -5 503 M -( uint32 version) s -5 481 M -( Version 3 of this protocol allowed clients to include extensions in) s -5 470 M -( the SSH_FXP_INIT packet; however, this can cause interoperability) s -5 459 M -( problems with version 1 and version 2 servers because the client must) s -5 448 M -( send this packet before knowing the servers version.) s -5 426 M -( In this version of the protocol, clients MUST use the) s -5 415 M -( SSH_FXP_EXTENDED packet to send extensions to the server after) s -5 404 M -( version exchange has completed. Clients MUST NOT include extensions) s -5 393 M -( in the version packet. This will prevent interoperability problems) s -5 382 M -( with older servers) s -5 360 M -(4.2 Server Initialization) s -5 338 M -( The SSH_FXP_VERSION packet \(from server to client\) has the following) s -5 327 M -( data:) s -5 305 M -( uint32 version) s -5 294 M -( <extension data>) s -5 272 M -( 'version' is the lower of the protocol version supported by the) s -5 261 M -( server and the version number received from the client.) s -5 239 M -( The extension data may be empty, or may be a sequence of) s -5 217 M -( string extension_name) s -5 206 M -( string extension_data) s -5 184 M -( pairs \(both strings MUST always be present if one is, but the) s -5 173 M -( `extension_data' string may be of zero length\). If present, these) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 7]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 8 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -( strings indicate extensions to the baseline protocol. The) s -5 679 M -( `extension_name' field\(s\) identify the name of the extension. The) s -5 668 M -( name should be of the form "name@domain", where the domain is the DNS) s -5 657 M -( domain name of the organization defining the extension. Additional) s -5 646 M -( names that are not of this format may be defined later by the IETF.) s -5 635 M -( Implementations MUST silently ignore any extensions whose name they) s -5 624 M -( do not recognize.) s -5 602 M -(4.3 Determining Server Newline Convention) s -5 580 M -( In order to correctly process text files in a cross platform) s -5 569 M -( compatible way, the newline convention must be converted from that of) s -5 558 M -( the server to that of the client, or, during an upload, from that of) s -5 547 M -( the client to that of the server.) s -5 525 M -( Versions 3 and prior of this protocol made no provisions for) s -5 514 M -( processing text files. Many clients implemented some sort of) s -5 503 M -( conversion algorithm, but without either a 'canonical' on the wire) s -5 492 M -( format or knowledge of the servers newline convention, correct) s -5 481 M -( conversion was not always possible.) s -5 459 M -( Starting with Version 4, the SSH_FXF_TEXT file open flag \(Section) s -5 448 M -( 6.3\) makes it possible to request that the server translate a file to) s -5 437 M -( a 'canonical' on the wire format. This format uses \\r\\n as the line) s -5 426 M -( separator.) s -5 404 M -( Servers for systems using multiple newline characters \(for example,) s -5 393 M -( Mac OS X or VMS\) or systems using counted records, MUST translate to) s -5 382 M -( the canonical form.) s -5 360 M -( However, to ease the burden of implementation on servers that use a) s -5 349 M -( single, simple separator sequence, the following extension allows the) s -5 338 M -( canonical format to be changed.) s -5 316 M -( string "newline") s -5 305 M -( string new-canonical-separator \(usually "\\r" or "\\n" or "\\r\\n"\)) s -5 283 M -( All clients MUST support this extension.) s -5 261 M -( When processing text files, clients SHOULD NOT translate any) s -5 250 M -( character or sequence that is not an exact match of the servers) s -5 239 M -( newline separator.) s -5 217 M -( In particular, if the newline sequence being used is the canonical) s -5 206 M -( "\\r\\n" sequence, a lone \\r or a lone \\n SHOULD be written through) s -5 195 M -( without change.) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 8]) s -_R -S -PStoPSsaved restore -%%Page: (8,9) 5 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 9 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -(5. File Attributes) s -5 668 M -( A new compound data type is defined for encoding file attributes.) s -5 657 M -( The same encoding is used both when returning file attributes from) s -5 646 M -( the server and when sending file attributes to the server. When) s -5 635 M -( sending it to the server, the flags field specifies which attributes) s -5 624 M -( are included, and the server will use default values for the) s -5 613 M -( remaining attributes \(or will not modify the values of remaining) s -5 602 M -( attributes\). When receiving attributes from the server, the flags) s -5 591 M -( specify which attributes are included in the returned data. The) s -5 580 M -( server normally returns all attributes it knows about.) s -5 558 M -( uint32 flags) s -5 547 M -( byte type always present) s -5 536 M -( uint64 size present only if flag SSH_FILEXFER_ATTR_SIZE) s -5 525 M -( string owner present only if flag SSH_FILEXFER_ATTR_OWNERGROUP) s -5 514 M -( string group present only if flag SSH_FILEXFER_ATTR_OWNERGROUP) s -5 503 M -( uint32 permissions present only if flag SSH_FILEXFER_ATTR_PERMISSIONS) s -5 492 M -( uint32 atime present only if flag SSH_FILEXFER_ATTR_ACCESSTIME) s -5 481 M -( uint32 createtime present only if flag SSH_FILEXFER_ATTR_CREATETIME) s -5 470 M -( uint32 mtime present only if flag SSH_FILEXFER_ATTR_MODIFYTIME) s -5 459 M -( string acl present only if flag SSH_FILEXFER_ATTR_ACL) s -5 448 M -( uint32 extended_count present only if flag SSH_FILEXFER_ATTR_EXTENDED) s -5 437 M -( string extended_type) s -5 426 M -( string extended_data) s -5 415 M -( ... more extended data \(extended_type - extended_data pairs\),) s -5 404 M -( so that number of pairs equals extended_count) s -5 371 M -(5.1 Flags) s -5 349 M -( The `flags' specify which of the fields are present. Those fields) s -5 338 M -( for which the corresponding flag is not set are not present \(not) s -5 327 M -( included in the packet\). New flags can only be added by incrementing) s -5 316 M -( the protocol version number \(or by using the extension mechanism) s -5 305 M -( described below\).) s -5 283 M -( The flags bits are defined to have the following values:) s -5 261 M -( #define SSH_FILEXFER_ATTR_SIZE 0x00000001) s -5 250 M -( #define SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004) s -5 239 M -( #define SSH_FILEXFER_ATTR_ACCESSTIME 0x00000008) s -5 228 M -( #define SSH_FILEXFER_ATTR_CREATETIME 0x00000010) s -5 217 M -( #define SSH_FILEXFER_ATTR_MODIFYTIME 0x00000020) s -5 206 M -( #define SSH_FILEXFER_ATTR_ACL 0x00000040) s -5 195 M -( #define SSH_FILEXFER_ATTR_OWNERGROUP 0x00000080) s -5 184 M -( #define SSH_FILEXFER_ATTR_EXTENDED 0x80000000) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 9]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 10 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -( In previous versions of this protocol flags value 0x00000002 was) s -5 679 M -( SSH_FILEXFER_ATTR_UIDGID. This value is now unused, and OWNERGROUP) s -5 668 M -( was given a new value in order to ease implementation burden.) s -5 657 M -( 0x00000002 MUST NOT appear in the mask. Some future version of this) s -5 646 M -( protocol may reuse flag 0x00000002.) s -5 624 M -(5.2 Type) s -5 602 M -( The type field is always present. The following types are defined:) s -5 580 M -( #define SSH_FILEXFER_TYPE_REGULAR 1) s -5 569 M -( #define SSH_FILEXFER_TYPE_DIRECTORY 2) s -5 558 M -( #define SSH_FILEXFER_TYPE_SYMLINK 3) s -5 547 M -( #define SSH_FILEXFER_TYPE_SPECIAL 4) s -5 536 M -( #define SSH_FILEXFER_TYPE_UNKNOWN 5) s -5 514 M -( On a POSIX system, these values would be derived from the permission) s -5 503 M -( field.) s -5 481 M -(5.3 Size) s -5 459 M -( The `size' field specifies the size of the file on disk, in bytes.) s -5 448 M -( If it is present during file creation, it should be considered a hint) s -5 437 M -( as to the files eventual size.) s -5 415 M -( Files opened with the SSH_FXF_TEXT flag may have a size that is) s -5 404 M -( greater or less than the value of the size field.) s -5 382 M -(5.4 Owner and Group) s -5 360 M -( The `owner' and `group' fields are represented as UTF-8 strings; this) s -5 349 M -( is the form used by NFS v4. See NFS version 4 Protocol. [3] The) s -5 338 M -( following text is selected quotations from section 5.6.) s -5 316 M -( To avoid a representation that is tied to a particular underlying) s -5 305 M -( implementation at the client or server, the use of UTF-8 strings has) s -5 294 M -( been chosen. The string should be of the form user@dns_domain".) s -5 283 M -( This will allow for a client and server that do not use the same) s -5 272 M -( local representation the ability to translate to a common syntax that) s -5 261 M -( can be interpreted by both. In the case where there is no) s -5 250 M -( translation available to the client or server, the attribute value) s -5 239 M -( must be constructed without the "@". Therefore, the absence of the @) s -5 228 M -( from the owner or owner_group attribute signifies that no translation) s -5 217 M -( was available and the receiver of the attribute should not place any) s -5 206 M -( special meaning with the attribute value. Even though the attribute) s -5 195 M -( value can not be translated, it may still be useful. In the case of) s -5 184 M -( a client, the attribute string may be used for local display of) s -5 173 M -( ownership.) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 10]) s -_R -S -PStoPSsaved restore -%%Page: (10,11) 6 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 11 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -(5.5 Permissions) s -5 668 M -( The `permissions' field contains a bit mask of file permissions as) s -5 657 M -( defined by POSIX [1].) s -5 635 M -(5.6 Times) s -5 613 M -( The 'atime', 'createtime', and 'mtime' contain the access, creation,) s -5 602 M -( and modification times of the files, respectively. They are) s -5 591 M -( represented as seconds from Jan 1, 1970 in UTC.) s -5 569 M -(5.7 ACL) s -5 547 M -( The 'ACL' field contains an ACL similar to that defined in section) s -5 536 M -( 5.9 of NFS version 4 Protocol [3].) s -5 514 M -( uint32 ace-count) s -5 492 M -( repeated ace-count time:) s -5 481 M -( uint32 ace-type) s -5 470 M -( uint32 ace-flag) s -5 459 M -( uint32 ace-mask) s -5 448 M -( string who [UTF-8]) s -5 426 M -( ace-type is one of the following four values \(taken from NFS Version) s -5 415 M -( 4 Protocol [3]:) s -5 393 M -( const ACE4_ACCESS_ALLOWED_ACE_TYPE = 0x00000000;) s -5 382 M -( const ACE4_ACCESS_DENIED_ACE_TYPE = 0x00000001;) s -5 371 M -( const ACE4_SYSTEM_AUDIT_ACE_TYPE = 0x00000002;) s -5 360 M -( const ACE4_SYSTEM_ALARM_ACE_TYPE = 0x00000003;) s -5 338 M -( ace-flag is a combination of the following flag values. See NFS) s -5 327 M -( Version 4 Protocol [3] section 5.9.2:) s -5 305 M -( const ACE4_FILE_INHERIT_ACE = 0x00000001;) s -5 294 M -( const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002;) s -5 283 M -( const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004;) s -5 272 M -( const ACE4_INHERIT_ONLY_ACE = 0x00000008;) s -5 261 M -( const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010;) s -5 250 M -( const ACE4_FAILED_ACCESS_ACE_FLAG = 0x00000020;) s -5 239 M -( const ACE4_IDENTIFIER_GROUP = 0x00000040;) s -5 217 M -( ace-mask is any combination of the following flags \(taken from NFS) s -5 206 M -( Version 4 Protocol [3] section 5.9.3:) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 11]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 12 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -( const ACE4_READ_DATA = 0x00000001;) s -5 679 M -( const ACE4_LIST_DIRECTORY = 0x00000001;) s -5 668 M -( const ACE4_WRITE_DATA = 0x00000002;) s -5 657 M -( const ACE4_ADD_FILE = 0x00000002;) s -5 646 M -( const ACE4_APPEND_DATA = 0x00000004;) s -5 635 M -( const ACE4_ADD_SUBDIRECTORY = 0x00000004;) s -5 624 M -( const ACE4_READ_NAMED_ATTRS = 0x00000008;) s -5 613 M -( const ACE4_WRITE_NAMED_ATTRS = 0x00000010;) s -5 602 M -( const ACE4_EXECUTE = 0x00000020;) s -5 591 M -( const ACE4_DELETE_CHILD = 0x00000040;) s -5 580 M -( const ACE4_READ_ATTRIBUTES = 0x00000080;) s -5 569 M -( const ACE4_WRITE_ATTRIBUTES = 0x00000100;) s -5 558 M -( const ACE4_DELETE = 0x00010000;) s -5 547 M -( const ACE4_READ_ACL = 0x00020000;) s -5 536 M -( const ACE4_WRITE_ACL = 0x00040000;) s -5 525 M -( const ACE4_WRITE_OWNER = 0x00080000;) s -5 514 M -( const ACE4_SYNCHRONIZE = 0x00100000;) s -5 492 M -( who is a UTF-8 string of the form described in 'Owner and Group') s -5 481 M -( \(Section 5.4\)) s -5 459 M -(5.8 Extended attributes) s -5 437 M -( The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension) s -5 426 M -( mechanism for vendor-specific extensions. If the flag is specified,) s -5 415 M -( then the `extended_count' field is present. It specifies the number) s -5 404 M -( of extended_type-extended_data pairs that follow. Each of these) s -5 393 M -( pairs specifies an extended attribute. For each of the attributes,) s -5 382 M -( the extended_type field should be a string of the format) s -5 371 M -( "name@domain", where "domain" is a valid, registered domain name and) s -5 360 M -( "name" identifies the method. The IETF may later standardize certain) s -5 349 M -( names that deviate from this format \(e.g., that do not contain the) s -5 338 M -( "@" sign\). The interpretation of `extended_data' depends on the) s -5 327 M -( type. Implementations SHOULD ignore extended data fields that they) s -5 316 M -( do not understand.) s -5 294 M -( Additional fields can be added to the attributes by either defining) s -5 283 M -( additional bits to the flags field to indicate their presence, or by) s -5 272 M -( defining extended attributes for them. The extended attributes) s -5 261 M -( mechanism is recommended for most purposes; additional flags bits) s -5 250 M -( should only be defined by an IETF standards action that also) s -5 239 M -( increments the protocol version number. The use of such new fields) s -5 228 M -( MUST be negotiated by the version number in the protocol exchange.) s -5 217 M -( It is a protocol error if a packet with unsupported protocol bits is) s -5 206 M -( received.) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 12]) s -_R -S -PStoPSsaved restore -%%Page: (12,13) 7 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 13 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -(6. Requests From the Client to the Server) s -5 668 M -( Requests from the client to the server represent the various file) s -5 657 M -( system operations. Each request begins with an `id' field, which is) s -5 646 M -( a 32-bit identifier identifying the request \(selected by the client\).) s -5 635 M -( The same identifier will be returned in the response to the request.) s -5 624 M -( One possible implementation is a monotonically increasing request) s -5 613 M -( sequence number \(modulo 2^32\).) s -5 591 M -( Many operations in the protocol operate on open files. The) s -5 580 M -( SSH_FXP_OPEN request can return a file handle \(which is an opaque) s -5 569 M -( variable-length string\) which may be used to access the file later) s -5 558 M -( \(e.g. in a read operation\). The client MUST NOT send requests the) s -5 547 M -( server with bogus or closed handles. However, the server MUST) s -5 536 M -( perform adequate checks on the handle in order to avoid security) s -5 525 M -( risks due to fabricated handles.) s -5 503 M -( This design allows either stateful and stateless server) s -5 492 M -( implementation, as well as an implementation which caches state) s -5 481 M -( between requests but may also flush it. The contents of the file) s -5 470 M -( handle string are entirely up to the server and its design. The) s -5 459 M -( client should not modify or attempt to interpret the file handle) s -5 448 M -( strings.) s -5 426 M -( The file handle strings MUST NOT be longer than 256 bytes.) s -5 404 M -(6.1 Request Synchronization and Reordering) s -5 382 M -( The protocol and implementations MUST process requests relating to) s -5 371 M -( the same file in the order in which they are received. In other) s -5 360 M -( words, if an application submits multiple requests to the server, the) s -5 349 M -( results in the responses will be the same as if it had sent the) s -5 338 M -( requests one at a time and waited for the response in each case. For) s -5 327 M -( example, the server may process non-overlapping read/write requests) s -5 316 M -( to the same file in parallel, but overlapping reads and writes cannot) s -5 305 M -( be reordered or parallelized. However, there are no ordering) s -5 294 M -( restrictions on the server for processing requests from two different) s -5 283 M -( file transfer connections. The server may interleave and parallelize) s -5 272 M -( them at will.) s -5 250 M -( There are no restrictions on the order in which responses to) s -5 239 M -( outstanding requests are delivered to the client, except that the) s -5 228 M -( server must ensure fairness in the sense that processing of no) s -5 217 M -( request will be indefinitely delayed even if the client is sending) s -5 206 M -( other requests so that there are multiple outstanding requests all) s -5 195 M -( the time.) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 13]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 14 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -(6.2 File Names) s -5 668 M -( This protocol represents file names as strings. File names are) s -5 657 M -( assumed to use the slash \('/'\) character as a directory separator.) s -5 635 M -( File names starting with a slash are "absolute", and are relative to) s -5 624 M -( the root of the file system. Names starting with any other character) s -5 613 M -( are relative to the user's default directory \(home directory\). Note) s -5 602 M -( that identifying the user is assumed to take place outside of this) s -5 591 M -( protocol.) s -5 569 M -( Servers SHOULD interpret a path name component ".." as referring to) s -5 558 M -( the parent directory, and "." as referring to the current directory.) s -5 547 M -( If the server implementation limits access to certain parts of the) s -5 536 M -( file system, it must be extra careful in parsing file names when) s -5 525 M -( enforcing such restrictions. There have been numerous reported) s -5 514 M -( security bugs where a ".." in a path name has allowed access outside) s -5 503 M -( the intended area.) s -5 481 M -( An empty path name is valid, and it refers to the user's default) s -5 470 M -( directory \(usually the user's home directory\).) s -5 448 M -( Otherwise, no syntax is defined for file names by this specification.) s -5 437 M -( Clients should not make any other assumptions; however, they can) s -5 426 M -( splice path name components returned by SSH_FXP_READDIR together) s -5 415 M -( using a slash \('/'\) as the separator, and that will work as expected.) s -5 393 M -( In order to comply with IETF Policy on Character Sets and Languages) s -5 382 M -( [2], all filenames are to be encoded in UTF-8. The shortest valid) s -5 371 M -( UTF-8 encoding of the UNICODE data MUST be used. The server is) s -5 360 M -( responsible for converting the UNICODE data to whatever canonical) s -5 349 M -( form it requires.) s -5 327 M -( For example, if the server requires that precomposed characters) s -5 316 M -( always be used, the server MUST NOT assume the filename as sent by) s -5 305 M -( the client has this attribute, but must do this normalization itself.) s -5 283 M -( It is understood that the lack of well-defined semantics for file) s -5 272 M -( names may cause interoperability problems between clients and servers) s -5 261 M -( using radically different operating systems. However, this approach) s -5 250 M -( is known to work acceptably with most systems, and alternative) s -5 239 M -( approaches that e.g. treat file names as sequences of structured) s -5 228 M -( components are quite complicated.) s -5 206 M -(6.3 Opening, Creating, and Closing Files) s -5 184 M -( Files are opened and created using the SSH_FXP_OPEN message, whose) s -5 173 M -( data part is as follows:) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 14]) s -_R -S -PStoPSsaved restore -%%Page: (14,15) 8 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 15 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -( uint32 id) s -5 679 M -( string filename [UTF-8]) s -5 668 M -( uint32 pflags) s -5 657 M -( ATTRS attrs) s -5 635 M -( The `id' field is the request identifier as for all requests.) s -5 613 M -( The `filename' field specifies the file name. See Section ``File) s -5 602 M -( Names'' for more information.) s -5 580 M -( The `pflags' field is a bitmask. The following bits have been) s -5 569 M -( defined.) s -5 547 M -( #define SSH_FXF_READ 0x00000001) s -5 536 M -( #define SSH_FXF_WRITE 0x00000002) s -5 525 M -( #define SSH_FXF_APPEND 0x00000004) s -5 514 M -( #define SSH_FXF_CREAT 0x00000008) s -5 503 M -( #define SSH_FXF_TRUNC 0x00000010) s -5 492 M -( #define SSH_FXF_EXCL 0x00000020) s -5 481 M -( #define SSH_FXF_TEXT 0x00000040) s -5 459 M -( These have the following meanings:) s -5 437 M -( SSH_FXF_READ) s -5 426 M -( Open the file for reading.) s -5 404 M -( SSH_FXF_WRITE) s -5 393 M -( Open the file for writing. If both this and SSH_FXF_READ are) s -5 382 M -( specified, the file is opened for both reading and writing.) s -5 360 M -( SSH_FXF_APPEND) s -5 349 M -( Force all writes to append data at the end of the file. The) s -5 338 M -( offset parameter to write will be ignored.) s -5 316 M -( SSH_FXF_CREAT) s -5 305 M -( If this flag is specified, then a new file will be created if one) s -5 294 M -( does not already exist \(if O_TRUNC is specified, the new file will) s -5 283 M -( be truncated to zero length if it previously exists\).) s -5 261 M -( SSH_FXF_TRUNC) s -5 250 M -( Forces an existing file with the same name to be truncated to zero) s -5 239 M -( length when creating a file by specifying SSH_FXF_CREAT.) s -5 228 M -( SSH_FXF_CREAT MUST also be specified if this flag is used.) s -5 206 M -( SSH_FXF_EXCL) s -5 195 M -( Causes the request to fail if the named file already exists.) s -5 184 M -( SSH_FXF_CREAT MUST also be specified if this flag is used.) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 15]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 16 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -( SSH_FXF_TEXT) s -5 679 M -( Indicates that the server should treat the file as text and) s -5 668 M -( convert it to the canonical newline convention in use. \(See) s -5 657 M -( Determining Server Newline Convention. \(Section 4.3\)) s -5 635 M -( When a file is opened with the FXF_TEXT flag, the offset field in) s -5 624 M -( both the read and write function are ignored.) s -5 602 M -( Servers MUST correctly process multiple parallel reads and writes) s -5 591 M -( correctly in this mode. Naturally, it is permissible for them to) s -5 580 M -( do this by serializing the requests. It would not be possible for) s -5 569 M -( a client to reliably detect a server that does not implement) s -5 558 M -( parallel writes in time to prevent damage.) s -5 536 M -( Clients SHOULD use the SSH_FXF_APPEND flag to append data to a) s -5 525 M -( text file rather then using write with a calculated offset.) s -5 503 M -( To support seeks on text file the following SSH_FXP_EXTENDED) s -5 492 M -( packet is defined.) s -5 448 M -( string "text-seek") s -5 437 M -( string file-handle) s -5 426 M -( uint64 line-number) s -5 404 M -( line-number is the index of the line number to seek to, where byte) s -5 393 M -( 0 in the file is line number 0, and the byte directly following) s -5 382 M -( the first newline sequence in the file is line number 1 and so on.) s -5 360 M -( The response to a "text-seek" request is an SSH_FXP_STATUS) s -5 349 M -( message.) s -5 327 M -( An attempt to seek past the end-of-file should result in a) s -5 316 M -( SSH_FX_EOF status.) s -5 294 M -( Servers SHOULD support at least one "text-seek" in order to) s -5 283 M -( support resume. However, a client MUST be prepared to receive) s -5 272 M -( SSH_FX_OP_UNSUPPORTED when attempting a "text-seek" operation.) s -5 261 M -( The client can then try a fall-back strategy, if it has one.) s -5 239 M -( Clients MUST be prepared to handle SSH_FX_OP_UNSUPPORTED returned) s -5 228 M -( for read or write operations that are not sequential.) s -5 206 M -( The `attrs' field specifies the initial attributes for the file.) s -5 195 M -( Default values will be used for those attributes that are not) s -5 184 M -( specified. See Section ``File Attributes'' for more information.) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 16]) s -_R -S -PStoPSsaved restore -%%Page: (16,17) 9 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 17 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -( The response to this message will be either SSH_FXP_HANDLE \(if the) s -5 679 M -( operation is successful\) or SSH_FXP_STATUS \(if the operation fails\).) s -5 657 M -( A file is closed by using the SSH_FXP_CLOSE request. Its data field) s -5 646 M -( has the following format:) s -5 624 M -( uint32 id) s -5 613 M -( string handle) s -5 591 M -( where `id' is the request identifier, and `handle' is a handle) s -5 580 M -( previously returned in the response to SSH_FXP_OPEN or) s -5 569 M -( SSH_FXP_OPENDIR. The handle becomes invalid immediately after this) s -5 558 M -( request has been sent.) s -5 536 M -( The response to this request will be a SSH_FXP_STATUS message. One) s -5 525 M -( should note that on some server platforms even a close can fail.) s -5 514 M -( This can happen e.g. if the server operating system caches writes,) s -5 503 M -( and an error occurs while flushing cached writes during the close.) s -5 481 M -(6.4 Reading and Writing) s -5 459 M -( Once a file has been opened, it can be read using the SSH_FXP_READ) s -5 448 M -( message, which has the following format:) s -5 426 M -( uint32 id) s -5 415 M -( string handle) s -5 404 M -( uint64 offset) s -5 393 M -( uint32 len) s -5 371 M -( where `id' is the request identifier, `handle' is an open file handle) s -5 360 M -( returned by SSH_FXP_OPEN, `offset' is the offset \(in bytes\) relative) s -5 349 M -( to the beginning of the file from where to start reading, and `len') s -5 338 M -( is the maximum number of bytes to read.) s -5 316 M -( In response to this request, the server will read as many bytes as it) s -5 305 M -( can from the file \(up to `len'\), and return them in a SSH_FXP_DATA) s -5 294 M -( message. If an error occurs or EOF is encountered before reading any) s -5 283 M -( data, the server will respond with SSH_FXP_STATUS. For normal disk) s -5 272 M -( files, it is guaranteed that this will read the specified number of) s -5 261 M -( bytes, or up to end of file. For e.g. device files this may return) s -5 250 M -( fewer bytes than requested.) s -5 228 M -( Writing to a file is achieved using the SSH_FXP_WRITE message, which) s -5 217 M -( has the following format:) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 17]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 18 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -( uint32 id) s -5 679 M -( string handle) s -5 668 M -( uint64 offset) s -5 657 M -( string data) s -5 635 M -( where `id' is a request identifier, `handle' is a file handle) s -5 624 M -( returned by SSH_FXP_OPEN, `offset' is the offset \(in bytes\) from the) s -5 613 M -( beginning of the file where to start writing, and `data' is the data) s -5 602 M -( to be written.) s -5 580 M -( The write will extend the file if writing beyond the end of the file.) s -5 569 M -( It is legal to write way beyond the end of the file; the semantics) s -5 558 M -( are to write zeroes from the end of the file to the specified offset) s -5 547 M -( and then the data. On most operating systems, such writes do not) s -5 536 M -( allocate disk space but instead leave "holes" in the file.) s -5 514 M -( The server responds to a write request with a SSH_FXP_STATUS message.) s -5 492 M -(6.5 Removing and Renaming Files) s -5 470 M -( Files can be removed using the SSH_FXP_REMOVE message. It has the) s -5 459 M -( following format:) s -5 437 M -( uint32 id) s -5 426 M -( string filename [UTF-8]) s -5 404 M -( where `id' is the request identifier and `filename' is the name of) s -5 393 M -( the file to be removed. See Section ``File Names'' for more) s -5 382 M -( information. This request cannot be used to remove directories.) s -5 360 M -( The server will respond to this request with a SSH_FXP_STATUS) s -5 349 M -( message.) s -5 327 M -( Files \(and directories\) can be renamed using the SSH_FXP_RENAME) s -5 316 M -( message. Its data is as follows:) s -5 294 M -( uint32 id) s -5 283 M -( string oldpath [UTF-8]) s -5 272 M -( string newpath [UTF-8]) s -5 250 M -( where `id' is the request identifier, `oldpath' is the name of an) s -5 239 M -( existing file or directory, and `newpath' is the new name for the) s -5 228 M -( file or directory. It is an error if there already exists a file) s -5 217 M -( with the name specified by newpath. The server may also fail rename) s -5 206 M -( requests in other situations, for example if `oldpath' and `newpath') s -5 195 M -( point to different file systems on the server.) s -5 173 M -( The server will respond to this request with a SSH_FXP_STATUS) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 18]) s -_R -S -PStoPSsaved restore -%%Page: (18,19) 10 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 19 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -( message.) s -5 668 M -(6.6 Creating and Deleting Directories) s -5 646 M -( New directories can be created using the SSH_FXP_MKDIR request. It) s -5 635 M -( has the following format:) s -5 613 M -( uint32 id) s -5 602 M -( string path [UTF-8]) s -5 591 M -( ATTRS attrs) s -5 569 M -( where `id' is the request identifier.) s -5 547 M -( `path' specifies the directory to be created. See Section ``File) s -5 536 M -( Names'' for more information on file names.) s -5 514 M -( `attrs' specifies the attributes that should be applied to it upon) s -5 503 M -( creation. Attributes are discussed in more detail in Section ``File) s -5 492 M -( Attributes''.) s -5 470 M -( The server will respond to this request with a SSH_FXP_STATUS) s -5 459 M -( message. If a file or directory with the specified path already) s -5 448 M -( exists, an error will be returned.) s -5 426 M -( Directories can be removed using the SSH_FXP_RMDIR request, which has) s -5 415 M -( the following format:) s -5 393 M -( uint32 id) s -5 382 M -( string path [UTF-8]) s -5 360 M -( where `id' is the request identifier, and `path' specifies the) s -5 349 M -( directory to be removed. See Section ``File Names'' for more) s -5 338 M -( information on file names.) s -5 316 M -( The server responds to this request with a SSH_FXP_STATUS message.) s -5 305 M -( Errors may be returned from this operation for various reasons,) s -5 294 M -( including, but not limited to, the path does not exist, the path does) s -5 283 M -( not refer to a directory object, the directory is not empty, or the) s -5 272 M -( user has insufficient access or permission to perform the requested) s -5 261 M -( operation.) s -5 239 M -(6.7 Scanning Directories) s -5 217 M -( The files in a directory can be listed using the SSH_FXP_OPENDIR and) s -5 206 M -( SSH_FXP_READDIR requests. Each SSH_FXP_READDIR request returns one) s -5 195 M -( or more file names with full file attributes for each file. The) s -5 184 M -( client should call SSH_FXP_READDIR repeatedly until it has found the) s -5 173 M -( file it is looking for or until the server responds with a) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 19]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 20 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -( SSH_FXP_STATUS message indicating an error \(normally SSH_FX_EOF if) s -5 679 M -( there are no more files in the directory\). The client should then) s -5 668 M -( close the handle using the SSH_FXP_CLOSE request.) s -5 646 M -( The SSH_FXP_OPENDIR opens a directory for reading. It has the) s -5 635 M -( following format:) s -5 613 M -( uint32 id) s -5 602 M -( string path [UTF-8]) s -5 580 M -( where `id' is the request identifier and `path' is the path name of) s -5 569 M -( the directory to be listed \(without any trailing slash\). See Section) s -5 558 M -( ``File Names'' for more information on file names. This will return) s -5 547 M -( an error if the path does not specify a directory or if the directory) s -5 536 M -( is not readable. The server will respond to this request with either) s -5 525 M -( a SSH_FXP_HANDLE or a SSH_FXP_STATUS message.) s -5 503 M -( Once the directory has been successfully opened, files \(and) s -5 492 M -( directories\) contained in it can be listed using SSH_FXP_READDIR) s -5 481 M -( requests. These are of the format) s -5 459 M -( uint32 id) s -5 448 M -( string handle) s -5 426 M -( where `id' is the request identifier, and `handle' is a handle) s -5 415 M -( returned by SSH_FXP_OPENDIR. \(It is a protocol error to attempt to) s -5 404 M -( use an ordinary file handle returned by SSH_FXP_OPEN.\)) s -5 382 M -( The server responds to this request with either a SSH_FXP_NAME or a) s -5 371 M -( SSH_FXP_STATUS message. One or more names may be returned at a time.) s -5 360 M -( Full status information is returned for each name in order to speed) s -5 349 M -( up typical directory listings.) s -5 327 M -( If there are no more names available to be read, the server MUST) s -5 316 M -( respond with a SSH_FXP_STATUS message with error code of SSH_FX_EOF.) s -5 294 M -( When the client no longer wishes to read more names from the) s -5 283 M -( directory, it SHOULD call SSH_FXP_CLOSE for the handle. The handle) s -5 272 M -( should be closed regardless of whether an error has occurred or not.) s -5 250 M -(6.8 Retrieving File Attributes) s -5 228 M -( Very often, file attributes are automatically returned by) s -5 217 M -( SSH_FXP_READDIR. However, sometimes there is need to specifically) s -5 206 M -( retrieve the attributes for a named file. This can be done using the) s -5 195 M -( SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests.) s -5 173 M -( SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 20]) s -_R -S -PStoPSsaved restore -%%Page: (20,21) 11 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 21 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -( follows symbolic links on the server, whereas SSH_FXP_LSTAT does not) s -5 679 M -( follow symbolic links. Both have the same format:) s -5 657 M -( uint32 id) s -5 646 M -( string path [UTF-8]) s -5 635 M -( uint32 flags) s -5 613 M -( where `id' is the request identifier, and `path' specifies the file) s -5 602 M -( system object for which status is to be returned. The server) s -5 591 M -( responds to this request with either SSH_FXP_ATTRS or SSH_FXP_STATUS.) s -5 569 M -( The flags field specify the attribute flags in which the client has) s -5 558 M -( particular interest. This is a hint to the server. For example,) s -5 547 M -( because retrieving owner / group and acl information can be an) s -5 536 M -( expensive operation under some operating systems, the server may) s -5 525 M -( choose not to retrieve this information unless the client expresses a) s -5 514 M -( specific interest in it.) s -5 492 M -( The client has no guarantee the server will provide all the fields) s -5 481 M -( that it has expressed an interest in.) s -5 459 M -( SSH_FXP_FSTAT differs from the others in that it returns status) s -5 448 M -( information for an open file \(identified by the file handle\). Its) s -5 437 M -( format is as follows:) s -5 415 M -( uint32 id) s -5 404 M -( string handle) s -5 393 M -( uint32 flags) s -5 371 M -( where `id' is the request identifier and `handle' is a file handle) s -5 360 M -( returned by SSH_FXP_OPEN. The server responds to this request with) s -5 349 M -( SSH_FXP_ATTRS or SSH_FXP_STATUS.) s -5 327 M -(6.9 Setting File Attributes) s -5 305 M -( File attributes may be modified using the SSH_FXP_SETSTAT and) s -5 294 M -( SSH_FXP_FSETSTAT requests. These requests are used for operations) s -5 283 M -( such as changing the ownership, permissions or access times, as well) s -5 272 M -( as for truncating a file.) s -5 250 M -( The SSH_FXP_SETSTAT request is of the following format:) s -5 228 M -( uint32 id) s -5 217 M -( string path [UTF-8]) s -5 206 M -( ATTRS attrs) s -5 184 M -( where `id' is the request identifier, `path' specifies the file) s -5 173 M -( system object \(e.g. file or directory\) whose attributes are to be) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 21]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 22 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -( modified, and `attrs' specifies the modifications to be made to its) s -5 679 M -( attributes. Attributes are discussed in more detail in Section) s -5 668 M -( ``File Attributes''.) s -5 646 M -( An error will be returned if the specified file system object does) s -5 635 M -( not exist or the user does not have sufficient rights to modify the) s -5 624 M -( specified attributes. The server responds to this request with a) s -5 613 M -( SSH_FXP_STATUS message.) s -5 591 M -( The SSH_FXP_FSETSTAT request modifies the attributes of a file which) s -5 580 M -( is already open. It has the following format:) s -5 558 M -( uint32 id) s -5 547 M -( string handle) s -5 536 M -( ATTRS attrs) s -5 514 M -( where `id' is the request identifier, `handle' \(MUST be returned by) s -5 503 M -( SSH_FXP_OPEN\) identifies the file whose attributes are to be) s -5 492 M -( modified, and `attrs' specifies the modifications to be made to its) s -5 481 M -( attributes. Attributes are discussed in more detail in Section) s -5 470 M -( ``File Attributes''. The server will respond to this request with) s -5 459 M -( SSH_FXP_STATUS.) s -5 437 M -(6.10 Dealing with Symbolic links) s -5 415 M -( The SSH_FXP_READLINK request may be used to read the target of a) s -5 404 M -( symbolic link. It would have a data part as follows:) s -5 382 M -( uint32 id) s -5 371 M -( string path [UTF-8]) s -5 349 M -( where `id' is the request identifier and `path' specifies the path) s -5 338 M -( name of the symlink to be read.) s -5 316 M -( The server will respond with a SSH_FXP_NAME packet containing only) s -5 305 M -( one name and a dummy attributes value. The name in the returned) s -5 294 M -( packet contains the target of the link. If an error occurs, the) s -5 283 M -( server may respond with SSH_FXP_STATUS.) s -5 261 M -( The SSH_FXP_SYMLINK request will create a symbolic link on the) s -5 250 M -( server. It is of the following format) s -5 228 M -( uint32 id) s -5 217 M -( string linkpath [UTF-8]) s -5 206 M -( string targetpath [UTF-8]) s -5 184 M -( where `id' is the request identifier, `linkpath' specifies the path) s -5 173 M -( name of the symlink to be created and `targetpath' specifies the) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 22]) s -_R -S -PStoPSsaved restore -%%Page: (22,23) 12 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 23 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -( target of the symlink. The server shall respond with a) s -5 679 M -( SSH_FXP_STATUS indicating either success \(SSH_FX_OK\) or an error) s -5 668 M -( condition.) s -5 646 M -(6.11 Canonicalizing the Server-Side Path Name) s -5 624 M -( The SSH_FXP_REALPATH request can be used to have the server) s -5 613 M -( canonicalize any given path name to an absolute path. This is useful) s -5 602 M -( for converting path names containing ".." components or relative) s -5 591 M -( pathnames without a leading slash into absolute paths. The format of) s -5 580 M -( the request is as follows:) s -5 558 M -( uint32 id) s -5 547 M -( string path [UTF-8]) s -5 525 M -( where `id' is the request identifier and `path' specifies the path) s -5 514 M -( name to be canonicalized. The server will respond with a) s -5 503 M -( SSH_FXP_NAME packet containing the name in canonical form and a dummy) s -5 492 M -( attributes value. If an error occurs, the server may also respond) s -5 481 M -( with SSH_FXP_STATUS.) s -5 459 M -(6.11.1 Best practice for dealing with paths) s -5 437 M -( The client SHOULD treat the results of SSH_FXP_REALPATH as a) s -5 426 M -( canonical absolute path, even if the path does not appear to be) s -5 415 M -( absolute. A client that use REALPATH\("."\) and treats the result as) s -5 404 M -( absolute, even if there is no leading slash, will continue to) s -5 393 M -( function correctly, even when talking to a Windows NT or VMS style) s -5 382 M -( system, where absolute paths may not begin with a slash.) s -5 360 M -( For example, if the client wishes to change directory up, and the) s -5 349 M -( server has returned "c:/x/y/z" from REALPATH, the client SHOULD use) s -5 338 M -( "c:/x/y/z/..".) s -5 316 M -( As a second example, if the client wishes to open the file "x.txt" in) s -5 305 M -( the current directory, and server has returned "dka100:/x/y/z" as the) s -5 294 M -( canonical path of the directory, the client SHOULD open "dka100:/x/y/) s -5 283 M -( z/x.txt") s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 23]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 24 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -(7. Responses from the Server to the Client) s -5 668 M -( The server responds to the client using one of a few response) s -5 657 M -( packets. All requests can return a SSH_FXP_STATUS response upon) s -5 646 M -( failure. When the operation is successful, any of the responses may) s -5 635 M -( be returned \(depending on the operation\). If no data needs to be) s -5 624 M -( returned to the client, the SSH_FXP_STATUS response with SSH_FX_OK) s -5 613 M -( status is appropriate. Otherwise, the SSH_FXP_HANDLE message is used) s -5 602 M -( to return a file handle \(for SSH_FXP_OPEN and SSH_FXP_OPENDIR) s -5 591 M -( requests\), SSH_FXP_DATA is used to return data from SSH_FXP_READ,) s -5 580 M -( SSH_FXP_NAME is used to return one or more file names from a) s -5 569 M -( SSH_FXP_READDIR or SSH_FXP_REALPATH request, and SSH_FXP_ATTRS is) s -5 558 M -( used to return file attributes from SSH_FXP_STAT, SSH_FXP_LSTAT, and) s -5 547 M -( SSH_FXP_FSTAT requests.) s -5 525 M -( Exactly one response will be returned for each request. Each) s -5 514 M -( response packet contains a request identifier which can be used to) s -5 503 M -( match each response with the corresponding request. Note that it is) s -5 492 M -( legal to have several requests outstanding simultaneously, and the) s -5 481 M -( server is allowed to send responses to them in a different order from) s -5 470 M -( the order in which the requests were sent \(the result of their) s -5 459 M -( execution, however, is guaranteed to be as if they had been processed) s -5 448 M -( one at a time in the order in which the requests were sent\).) s -5 426 M -( Response packets are of the same general format as request packets.) s -5 415 M -( Each response packet begins with the request identifier.) s -5 393 M -( The format of the data portion of the SSH_FXP_STATUS response is as) s -5 382 M -( follows:) s -5 360 M -( uint32 id) s -5 349 M -( uint32 error/status code) s -5 338 M -( string error message \(ISO-10646 UTF-8 [RFC-2279]\)) s -5 327 M -( string language tag \(as defined in [RFC-1766]\)) s -5 305 M -( where `id' is the request identifier, and `error/status code') s -5 294 M -( indicates the result of the requested operation. The value SSH_FX_OK) s -5 283 M -( indicates success, and all other values indicate failure.) s -5 261 M -( Currently, the following values are defined \(other values may be) s -5 250 M -( defined by future versions of this protocol\):) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 24]) s -_R -S -PStoPSsaved restore -%%Page: (24,25) 13 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 25 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -( #define SSH_FX_OK 0) s -5 679 M -( #define SSH_FX_EOF 1) s -5 668 M -( #define SSH_FX_NO_SUCH_FILE 2) s -5 657 M -( #define SSH_FX_PERMISSION_DENIED 3) s -5 646 M -( #define SSH_FX_FAILURE 4) s -5 635 M -( #define SSH_FX_BAD_MESSAGE 5) s -5 624 M -( #define SSH_FX_NO_CONNECTION 6) s -5 613 M -( #define SSH_FX_CONNECTION_LOST 7) s -5 602 M -( #define SSH_FX_OP_UNSUPPORTED 8) s -5 591 M -( #define SSH_FX_INVALID_HANDLE 9) s -5 580 M -( #define SSH_FX_NO_SUCH_PATH 10) s -5 569 M -( #define SSH_FX_FILE_ALREADY_EXISTS 11) s -5 558 M -( #define SSH_FX_WRITE_PROTECT 12) s -5 536 M -( SSH_FX_OK) s -5 525 M -( Indicates successful completion of the operation.) s -5 503 M -( SSH_FX_EOF) s -5 492 M -( indicates end-of-file condition; for SSH_FX_READ it means that no) s -5 481 M -( more data is available in the file, and for SSH_FX_READDIR it) s -5 470 M -( indicates that no more files are contained in the directory.) s -5 448 M -( SSH_FX_NO_SUCH_FILE) s -5 437 M -( is returned when a reference is made to a file which does not) s -5 426 M -( exist.) s -5 404 M -( SSH_FX_PERMISSION_DENIED) s -5 393 M -( is returned when the authenticated user does not have sufficient) s -5 382 M -( permissions to perform the operation.) s -5 360 M -( SSH_FX_FAILURE) s -5 349 M -( is a generic catch-all error message; it should be returned if an) s -5 338 M -( error occurs for which there is no more specific error code) s -5 327 M -( defined.) s -5 305 M -( SSH_FX_BAD_MESSAGE) s -5 294 M -( may be returned if a badly formatted packet or protocol) s -5 283 M -( incompatibility is detected.) s -5 261 M -( SSH_FX_NO_CONNECTION) s -5 250 M -( is a pseudo-error which indicates that the client has no) s -5 239 M -( connection to the server \(it can only be generated locally by the) s -5 228 M -( client, and MUST NOT be returned by servers\).) s -5 206 M -( SSH_FX_CONNECTION_LOST) s -5 195 M -( is a pseudo-error which indicates that the connection to the) s -5 184 M -( server has been lost \(it can only be generated locally by the) s -5 173 M -( client, and MUST NOT be returned by servers\).) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 25]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 26 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -( SSH_FX_OP_UNSUPPORTED) s -5 679 M -( indicates that an attempt was made to perform an operation which) s -5 668 M -( is not supported for the server \(it may be generated locally by) s -5 657 M -( the client if e.g. the version number exchange indicates that a) s -5 646 M -( required feature is not supported by the server, or it may be) s -5 635 M -( returned by the server if the server does not implement an) s -5 624 M -( operation\).) s -5 602 M -( SSH_FX_INVALID_HANDLE) s -5 591 M -( The handle value was invalid.) s -5 569 M -( SSH_FX_NO_SUCH_PATH) s -5 558 M -( The file path does not exist or is invalid.) s -5 536 M -( SSH_FX_FILE_ALREADY_EXISTS) s -5 525 M -( The file already exists.) s -5 503 M -( SSH_FX_WRITE_PROTECT) s -5 492 M -( The file is on read only media, or the media is write protected.) s -5 470 M -( The SSH_FXP_HANDLE response has the following format:) s -5 448 M -( uint32 id) s -5 437 M -( string handle) s -5 415 M -( where `id' is the request identifier, and `handle' is an arbitrary) s -5 404 M -( string that identifies an open file or directory on the server. The) s -5 393 M -( handle is opaque to the client; the client MUST NOT attempt to) s -5 382 M -( interpret or modify it in any way. The length of the handle string) s -5 371 M -( MUST NOT exceed 256 data bytes.) s -5 349 M -( The SSH_FXP_DATA response has the following format:) s -5 327 M -( uint32 id) s -5 316 M -( string data) s -5 294 M -( where `id' is the request identifier, and `data' is an arbitrary byte) s -5 283 M -( string containing the requested data. The data string may be at most) s -5 272 M -( the number of bytes requested in a SSH_FXP_READ request, but may also) s -5 261 M -( be shorter if end of file is reached or if the read is from something) s -5 250 M -( other than a regular file.) s -5 228 M -( The SSH_FXP_NAME response has the following format:) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 26]) s -_R -S -PStoPSsaved restore -%%Page: (26,27) 14 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 27 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -( uint32 id) s -5 679 M -( uint32 count) s -5 668 M -( repeats count times:) s -5 657 M -( string filename [UTF-8]) s -5 646 M -( ATTRS attrs) s -5 624 M -( where `id' is the request identifier, `count' is the number of names) s -5 613 M -( returned in this response, and the remaining fields repeat `count') s -5 602 M -( times \(so that all three fields are first included for the first) s -5 591 M -( file, then for the second file, etc\). In the repeated part,) s -5 580 M -( `filename' is a file name being returned \(for SSH_FXP_READDIR, it) s -5 569 M -( will be a relative name within the directory, without any path) s -5 558 M -( components; for SSH_FXP_REALPATH it will be an absolute path name\),) s -5 547 M -( and `attrs' is the attributes of the file as described in Section) s -5 536 M -( ``File Attributes''.) s -5 514 M -( The SSH_FXP_ATTRS response has the following format:) s -5 492 M -( uint32 id) s -5 481 M -( ATTRS attrs) s -5 459 M -( where `id' is the request identifier, and `attrs' is the returned) s -5 448 M -( file attributes as described in Section ``File Attributes''.) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 27]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 28 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -(8. Vendor-Specific Extensions) s -5 668 M -( The SSH_FXP_EXTENDED request provides a generic extension mechanism) s -5 657 M -( for adding vendor-specific commands. The request has the following) s -5 646 M -( format:) s -5 624 M -( uint32 id) s -5 613 M -( string extended-request) s -5 602 M -( ... any request-specific data ...) s -5 580 M -( where `id' is the request identifier, and `extended-request' is a) s -5 569 M -( string of the format "name@domain", where domain is an internet) s -5 558 M -( domain name of the vendor defining the request. The rest of the) s -5 547 M -( request is completely vendor-specific, and servers should only) s -5 536 M -( attempt to interpret it if they recognize the `extended-request') s -5 525 M -( name.) s -5 503 M -( The server may respond to such requests using any of the response) s -5 492 M -( packets defined in Section ``Responses from the Server to the) s -5 481 M -( Client''. Additionally, the server may also respond with a) s -5 470 M -( SSH_FXP_EXTENDED_REPLY packet, as defined below. If the server does) s -5 459 M -( not recognize the `extended-request' name, then the server MUST) s -5 448 M -( respond with SSH_FXP_STATUS with error/status set to) s -5 437 M -( SSH_FX_OP_UNSUPPORTED.) s -5 415 M -( The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary) s -5 404 M -( extension-specific data from the server to the client. It is of the) s -5 393 M -( following format:) s -5 371 M -( uint32 id) s -5 360 M -( ... any request-specific data ...) s -5 338 M -( There is a range of packet types reserved for use by extensions. In) s -5 327 M -( order to avoid collision, extensions that turn on the use of) s -5 316 M -( additional packet types should determine those numbers dynamically.) s -5 294 M -( The suggested way of doing this is have an extension request from the) s -5 283 M -( client to the server that enables the extension; the extension) s -5 272 M -( response from the server to the client would specify the actual type) s -5 261 M -( values to use, in additional to any other data.) s -5 239 M -( Extension authors should be mindful of the limited range of packet) s -5 228 M -( types available \(there are only 45 values available\) and avoid) s -5 217 M -( requiring a new packet type where possible.) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 28]) s -_R -S -PStoPSsaved restore -%%Page: (28,29) 15 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 29 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -(9. Security Considerations) s -5 668 M -( This protocol assumes that it is run over a secure channel and that) s -5 657 M -( the endpoints of the channel have been authenticated. Thus, this) s -5 646 M -( protocol assumes that it is externally protected from network-level) s -5 635 M -( attacks.) s -5 613 M -( This protocol provides file system access to arbitrary files on the) s -5 602 M -( server \(only constrained by the server implementation\). It is the) s -5 591 M -( responsibility of the server implementation to enforce any access) s -5 580 M -( controls that may be required to limit the access allowed for any) s -5 569 M -( particular user \(the user being authenticated externally to this) s -5 558 M -( protocol, typically using the SSH User Authentication Protocol [8].) s -5 536 M -( Care must be taken in the server implementation to check the validity) s -5 525 M -( of received file handle strings. The server should not rely on them) s -5 514 M -( directly; it MUST check the validity of each handle before relying on) s -5 503 M -( it.) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 29]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 30 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -(10. Changes from previous protocol versions) s -5 668 M -( The SSH File Transfer Protocol has changed over time, before it's) s -5 657 M -( standardization. The following is a description of the incompatible) s -5 646 M -( changes between different versions.) s -5 624 M -(10.1 Changes between versions 4 and 3) s -5 602 M -( Many of the changes between version 4 and version 3 are to the) s -5 591 M -( attribute structure to make it more flexible for non-unix platforms.) s -5 569 M -( o Make all filenames UTF-8.) s -5 547 M -( o Added 'newline' extension.) s -5 525 M -( o Made file attribute owner and group strings so they can actually) s -5 514 M -( be used on disparate systems.) s -5 492 M -( o Added createtime field, and added separate flags for atime,) s -5 481 M -( createtime, and mtime so they can be set separately.) s -5 459 M -( o Split the file type out of the permissions field and into it's own) s -5 448 M -( field \(which is always present.\)) s -5 426 M -( o Added acl attribute.) s -5 404 M -( o Added SSH_FXF_TEXT file open flag.) s -5 382 M -( o Added flags field to the get stat commands so that the client can) s -5 371 M -( specifically request information the server might not normally) s -5 360 M -( included for performance reasons.) s -5 338 M -( o Removed the long filename from the names structure-- it can now be) s -5 327 M -( built from information available in the attrs structure.) s -5 305 M -( o Added reserved range of packet numbers for extensions.) s -5 283 M -( o Added several additional error codes.) s -5 261 M -( o Change the way version negotiate works slightly. Previously, if) s -5 250 M -( the client version were higher than the server version, the server) s -5 239 M -( was supposed to 'echo back' the clients version. The server now) s -5 228 M -( sends it's own version and the lower of the two is considered to) s -5 217 M -( be the one in use.) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 30]) s -_R -S -PStoPSsaved restore -%%Page: (30,31) 16 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 31 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -(10.2 Changes between versions 3 and 2) s -5 668 M -( o The SSH_FXP_READLINK and SSH_FXP_SYMLINK messages were added.) s -5 646 M -( o The SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY messages were) s -5 635 M -( added.) s -5 613 M -( o The SSH_FXP_STATUS message was changed to include fields `error) s -5 602 M -( message' and `language tag'.) s -5 569 M -(10.3 Changes between versions 2 and 1) s -5 547 M -( o The SSH_FXP_RENAME message was added.) s -5 514 M -(10.4 Changes between versions 1 and 0) s -5 492 M -( o Implementation changes, no actual protocol changes.) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 31]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 32 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -(11. Trademark Issues) s -5 668 M -( "ssh" is a registered trademark of SSH Communications Security Corp) s -5 657 M -( in the United States and/or other countries.) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 32]) s -_R -S -PStoPSsaved restore -%%Page: (32,33) 17 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 33 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -(References) s -5 668 M -( [1] Dierks, T., Allen, C., Treese, W., Karlton, P., Freier, A. and) s -5 657 M -( P. Kocher, "The TLS Protocol Version 1.0", RFC 2246, January) s -5 646 M -( 1999.) s -5 624 M -( [2] Alvestrand, H., "IETF Policy on Character Sets and Languages",) s -5 613 M -( BCP 18, RFC 2277, January 1998.) s -5 591 M -( [3] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., Beame,) s -5 580 M -( C., Eisler, M. and D. Noveck, "NFS version 4 Protocol", RFC) s -5 569 M -( 3010, December 2000.) s -5 547 M -( [4] Institute of Electrical and Electronics Engineers, "Information) s -5 536 M -( Technology - Portable Operating System Interface \(POSIX\) - Part) s -5 525 M -( 1: System Application Program Interface \(API\) [C Language]",) s -5 514 M -( IEEE Standard 1003.2, 1996.) s -5 492 M -( [5] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.) s -5 481 M -( Lehtinen, "SSH Protocol Architecture", draft-ietf-secsh-) s -5 470 M -( architecture-13 \(work in progress\), September 2002.) s -5 448 M -( [6] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.) s -5 437 M -( Lehtinen, "SSH Protocol Transport Protocol", draft-ietf-secsh-) s -5 426 M -( transport-15 \(work in progress\), September 2002.) s -5 404 M -( [7] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.) s -5 393 M -( Lehtinen, "SSH Connection Protocol", draft-ietf-secsh-connect-16) s -5 382 M -( \(work in progress\), September 2002.) s -5 360 M -( [8] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.) s -5 349 M -( Lehtinen, "SSH Authentication Protocol", draft-ietf-secsh-) s -5 338 M -( userauth-16 \(work in progress\), September 2002.) s -5 305 M -(Authors' Addresses) s -5 283 M -( Joseph Galbraith) s -5 272 M -( VanDyke Software) s -5 261 M -( 4848 Tramway Ridge Blvd) s -5 250 M -( Suite 101) s -5 239 M -( Albuquerque, NM 87111) s -5 228 M -( US) s -5 206 M -( Phone: +1 505 332 5700) s -5 195 M -( EMail: [email protected]) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 33]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 34 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -( Tatu Ylonen) s -5 679 M -( SSH Communications Security Corp) s -5 668 M -( Fredrikinkatu 42) s -5 657 M -( HELSINKI FIN-00100) s -5 646 M -( Finland) s -5 624 M -( EMail: [email protected]) s -5 591 M -( Sami Lehtinen) s -5 580 M -( SSH Communications Security Corp) s -5 569 M -( Fredrikinkatu 42) s -5 558 M -( HELSINKI FIN-00100) s -5 547 M -( Finland) s -5 525 M -( EMail: [email protected]) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 34]) s -_R -S -PStoPSsaved restore -%%Page: (34,35) 18 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 35 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH File Transfer Protocol October 2002) s -5 690 M -(Full Copyright Statement) s -5 668 M -( Copyright \(C\) The Internet Society \(2002\). All Rights Reserved.) s -5 646 M -( This document and translations of it may be copied and furnished to) s -5 635 M -( others, and derivative works that comment on or otherwise explain it) s -5 624 M -( or assist in its implementation may be prepared, copied, published) s -5 613 M -( and distributed, in whole or in part, without restriction of any) s -5 602 M -( kind, provided that the above copyright notice and this paragraph are) s -5 591 M -( included on all such copies and derivative works. However, this) s -5 580 M -( document itself may not be modified in any way, such as by removing) s -5 569 M -( the copyright notice or references to the Internet Society or other) s -5 558 M -( Internet organizations, except as needed for the purpose of) s -5 547 M -( developing Internet standards in which case the procedures for) s -5 536 M -( copyrights defined in the Internet Standards process must be) s -5 525 M -( followed, or as required to translate it into languages other than) s -5 514 M -( English.) s -5 492 M -( The limited permissions granted above are perpetual and will not be) s -5 481 M -( revoked by the Internet Society or its successors or assigns.) s -5 459 M -( This document and the information contained herein is provided on an) s -5 448 M -( "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING) s -5 437 M -( TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING) s -5 426 M -( BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION) s -5 415 M -( HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF) s -5 404 M -( MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.) s -5 382 M -(Acknowledgement) s -5 360 M -( Funding for the RFC Editor function is currently provided by the) s -5 349 M -( Internet Society.) s -5 129 M -(Galbraith, et al. Expires April 16, 2003 [Page 35]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 36 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -_R -S -PStoPSsaved restore -%%Trailer -%%Pages: 36 -%%DocumentNeededResources: font Courier-Bold Courier -%%EOF diff --git a/lib/ssh/doc/standard/draft-ietf-secsh-filexfer-03.txt b/lib/ssh/doc/standard/draft-ietf-secsh-filexfer-03.txt deleted file mode 100644 index 83960ae976..0000000000 --- a/lib/ssh/doc/standard/draft-ietf-secsh-filexfer-03.txt +++ /dev/null @@ -1,1962 +0,0 @@ - - - -Secure Shell Working Group J. Galbraith -Internet-Draft VanDyke Software -Expires: April 16, 2003 T. Ylonen - S. Lehtinen - SSH Communications Security Corp - October 16, 2002 - - - SSH File Transfer Protocol - draft-ietf-secsh-filexfer-03.txt - -Status of this Memo - - This document is an Internet-Draft and is in full conformance with - all provisions of Section 10 of RFC2026. - - Internet-Drafts are working documents of the Internet Engineering - Task Force (IETF), its areas, and its working groups. Note that - other groups may also distribute working documents as Internet- - Drafts. - - Internet-Drafts are draft documents valid for a maximum of six months - and may be updated, replaced, or obsoleted by other documents at any - time. It is inappropriate to use Internet-Drafts as reference - material or to cite them other than as "work in progress." - - The list of current Internet-Drafts can be accessed at http:// - www.ietf.org/ietf/1id-abstracts.txt. - - The list of Internet-Draft Shadow Directories can be accessed at - http://www.ietf.org/shadow.html. - - This Internet-Draft will expire on April 16, 2003. - -Copyright Notice - - Copyright (C) The Internet Society (2002). All Rights Reserved. - -Abstract - - The SSH File Transfer Protocol provides secure file transfer - functionality over any reliable data stream. It is the standard file - transfer protocol for use with the SSH2 protocol. This document - describes the file transfer protocol and its interface to the SSH2 - protocol suite. - - - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 1] - -Internet-Draft SSH File Transfer Protocol October 2002 - - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 3 - 2. Use with the SSH Connection Protocol . . . . . . . . . . . 4 - 3. General Packet Format . . . . . . . . . . . . . . . . . . 5 - 4. Protocol Initialization . . . . . . . . . . . . . . . . . 7 - 4.1 Client Initialization . . . . . . . . . . . . . . . . . . 7 - 4.2 Server Initialization . . . . . . . . . . . . . . . . . . 7 - 4.3 Determining Server Newline Convention . . . . . . . . . . 8 - 5. File Attributes . . . . . . . . . . . . . . . . . . . . . 9 - 5.1 Flags . . . . . . . . . . . . . . . . . . . . . . . . . . 9 - 5.2 Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 - 5.3 Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 - 5.4 Owner and Group . . . . . . . . . . . . . . . . . . . . . 10 - 5.5 Permissions . . . . . . . . . . . . . . . . . . . . . . . 11 - 5.6 Times . . . . . . . . . . . . . . . . . . . . . . . . . . 11 - 5.7 ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 - 5.8 Extended attributes . . . . . . . . . . . . . . . . . . . 12 - 6. Requests From the Client to the Server . . . . . . . . . . 13 - 6.1 Request Synchronization and Reordering . . . . . . . . . . 13 - 6.2 File Names . . . . . . . . . . . . . . . . . . . . . . . . 14 - 6.3 Opening, Creating, and Closing Files . . . . . . . . . . . 14 - 6.4 Reading and Writing . . . . . . . . . . . . . . . . . . . 17 - 6.5 Removing and Renaming Files . . . . . . . . . . . . . . . 18 - 6.6 Creating and Deleting Directories . . . . . . . . . . . . 19 - 6.7 Scanning Directories . . . . . . . . . . . . . . . . . . . 19 - 6.8 Retrieving File Attributes . . . . . . . . . . . . . . . . 20 - 6.9 Setting File Attributes . . . . . . . . . . . . . . . . . 21 - 6.10 Dealing with Symbolic links . . . . . . . . . . . . . . . 22 - 6.11 Canonicalizing the Server-Side Path Name . . . . . . . . . 23 - 6.11.1 Best practice for dealing with paths . . . . . . . . . . . 23 - 7. Responses from the Server to the Client . . . . . . . . . 24 - 8. Vendor-Specific Extensions . . . . . . . . . . . . . . . . 28 - 9. Security Considerations . . . . . . . . . . . . . . . . . 29 - 10. Changes from previous protocol versions . . . . . . . . . 30 - 10.1 Changes between versions 4 and 3 . . . . . . . . . . . . . 30 - 10.2 Changes between versions 3 and 2 . . . . . . . . . . . . . 31 - 10.3 Changes between versions 2 and 1 . . . . . . . . . . . . . 31 - 10.4 Changes between versions 1 and 0 . . . . . . . . . . . . . 31 - 11. Trademark Issues . . . . . . . . . . . . . . . . . . . . . 32 - References . . . . . . . . . . . . . . . . . . . . . . . . 33 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . 33 - Full Copyright Statement . . . . . . . . . . . . . . . . . 35 - - - - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 2] - -Internet-Draft SSH File Transfer Protocol October 2002 - - -1. Introduction - - This protocol provides secure file transfer (and more generally file - system access) functionality over a reliable data stream, such as a - channel in the SSH2 protocol [5]. - - This protocol is designed so that it could be used to implement a - secure remote file system service, as well as a secure file transfer - service. - - This protocol assumes that it runs over a secure channel, and that - the server has already authenticated the user at the client end, and - that the identity of the client user is externally available to the - server implementation. - - In general, this protocol follows a simple request-response model. - Each request and response contains a sequence number and multiple - requests may be pending simultaneously. There are a relatively large - number of different request messages, but a small number of possible - response messages. Each request has one or more response messages - that may be returned in result (e.g., a read either returns data or - reports error status). - - The packet format descriptions in this specification follow the - notation presented in the secsh architecture draft. [5] - - Even though this protocol is described in the context of the SSH2 - protocol, this protocol is general and independent of the rest of the - SSH2 protocol suite. It could be used in a number of different - applications, such as secure file transfer over TLS RFC 2246 [1] and - transfer of management information in VPN applications. - - - - - - - - - - - - - - - - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 3] - -Internet-Draft SSH File Transfer Protocol October 2002 - - -2. Use with the SSH Connection Protocol - - When used with the SSH2 Protocol suite, this protocol is intended to - be used from the SSH Connection Protocol [7] as a subsystem, as - described in section ``Starting a Shell or a Command''. The - subsystem name used with this protocol is "sftp". - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 4] - -Internet-Draft SSH File Transfer Protocol October 2002 - - -3. General Packet Format - - All packets transmitted over the secure connection are of the - following format: - - uint32 length - byte type - byte[length - 1] data payload - - That is, they are just data preceded by 32-bit length and 8-bit type - fields. The `length' is the length of the data area, and does not - include the `length' field itself. The format and interpretation of - the data area depends on the packet type. - - All packet descriptions below only specify the packet type and the - data that goes into the data field. Thus, they should be prefixed by - the `length' and `type' fields. - - The maximum size of a packet is in practice determined by the client - (the maximum size of read or write requests that it sends, plus a few - bytes of packet overhead). All servers SHOULD support packets of at - least 34000 bytes (where the packet size refers to the full length, - including the header above). This should allow for reads and writes - of at most 32768 bytes. - - There is no limit on the number of outstanding (non-acknowledged) - requests that the client may send to the server. In practice this is - limited by the buffering available on the data stream and the queuing - performed by the server. If the server's queues are full, it should - not read any more data from the stream, and flow control will prevent - the client from sending more requests. Note, however, that while - there is no restriction on the protocol level, the client's API may - provide a limit in order to prevent infinite queuing of outgoing - requests at the client. - - The following values are defined for packet types. - - - - - - - - - - - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 5] - -Internet-Draft SSH File Transfer Protocol October 2002 - - - #define SSH_FXP_INIT 1 - #define SSH_FXP_VERSION 2 - #define SSH_FXP_OPEN 3 - #define SSH_FXP_CLOSE 4 - #define SSH_FXP_READ 5 - #define SSH_FXP_WRITE 6 - #define SSH_FXP_LSTAT 7 - #define SSH_FXP_FSTAT 8 - #define SSH_FXP_SETSTAT 9 - #define SSH_FXP_FSETSTAT 10 - #define SSH_FXP_OPENDIR 11 - #define SSH_FXP_READDIR 12 - #define SSH_FXP_REMOVE 13 - #define SSH_FXP_MKDIR 14 - #define SSH_FXP_RMDIR 15 - #define SSH_FXP_REALPATH 16 - #define SSH_FXP_STAT 17 - #define SSH_FXP_RENAME 18 - #define SSH_FXP_READLINK 19 - #define SSH_FXP_SYMLINK 20 - - #define SSH_FXP_STATUS 101 - #define SSH_FXP_HANDLE 102 - #define SSH_FXP_DATA 103 - #define SSH_FXP_NAME 104 - #define SSH_FXP_ATTRS 105 - - #define SSH_FXP_EXTENDED 200 - #define SSH_FXP_EXTENDED_REPLY 201 - - RESERVED_FOR_EXTENSIONS 210-255 - - Additional packet types should only be defined if the protocol - version number (see Section ``Protocol Initialization'') is - incremented, and their use MUST be negotiated using the version - number. However, the SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY - packets can be used to implement vendor-specific extensions. See - Section ``Vendor-Specific-Extensions'' for more details. - - - - - - - - - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 6] - -Internet-Draft SSH File Transfer Protocol October 2002 - - -4. Protocol Initialization - - When the file transfer protocol starts, the client first sends a - SSH_FXP_INIT (including its version number) packet to the server. - The server responds with a SSH_FXP_VERSION packet, supplying the - lowest of its own and the client's version number. Both parties - should from then on adhere to particular version of the protocol. - - The version number of the protocol specified in this document is 4. - The version number should be incremented for each incompatible - revision of this protocol. - -4.1 Client Initialization - - The SSH_FXP_INIT packet (from client to server) has the following - data: - - uint32 version - - Version 3 of this protocol allowed clients to include extensions in - the SSH_FXP_INIT packet; however, this can cause interoperability - problems with version 1 and version 2 servers because the client must - send this packet before knowing the servers version. - - In this version of the protocol, clients MUST use the - SSH_FXP_EXTENDED packet to send extensions to the server after - version exchange has completed. Clients MUST NOT include extensions - in the version packet. This will prevent interoperability problems - with older servers - -4.2 Server Initialization - - The SSH_FXP_VERSION packet (from server to client) has the following - data: - - uint32 version - <extension data> - - 'version' is the lower of the protocol version supported by the - server and the version number received from the client. - - The extension data may be empty, or may be a sequence of - - string extension_name - string extension_data - - pairs (both strings MUST always be present if one is, but the - `extension_data' string may be of zero length). If present, these - - - -Galbraith, et al. Expires April 16, 2003 [Page 7] - -Internet-Draft SSH File Transfer Protocol October 2002 - - - strings indicate extensions to the baseline protocol. The - `extension_name' field(s) identify the name of the extension. The - name should be of the form "name@domain", where the domain is the DNS - domain name of the organization defining the extension. Additional - names that are not of this format may be defined later by the IETF. - Implementations MUST silently ignore any extensions whose name they - do not recognize. - -4.3 Determining Server Newline Convention - - In order to correctly process text files in a cross platform - compatible way, the newline convention must be converted from that of - the server to that of the client, or, during an upload, from that of - the client to that of the server. - - Versions 3 and prior of this protocol made no provisions for - processing text files. Many clients implemented some sort of - conversion algorithm, but without either a 'canonical' on the wire - format or knowledge of the servers newline convention, correct - conversion was not always possible. - - Starting with Version 4, the SSH_FXF_TEXT file open flag (Section - 6.3) makes it possible to request that the server translate a file to - a 'canonical' on the wire format. This format uses \r\n as the line - separator. - - Servers for systems using multiple newline characters (for example, - Mac OS X or VMS) or systems using counted records, MUST translate to - the canonical form. - - However, to ease the burden of implementation on servers that use a - single, simple separator sequence, the following extension allows the - canonical format to be changed. - - string "newline" - string new-canonical-separator (usually "\r" or "\n" or "\r\n") - - All clients MUST support this extension. - - When processing text files, clients SHOULD NOT translate any - character or sequence that is not an exact match of the servers - newline separator. - - In particular, if the newline sequence being used is the canonical - "\r\n" sequence, a lone \r or a lone \n SHOULD be written through - without change. - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 8] - -Internet-Draft SSH File Transfer Protocol October 2002 - - -5. File Attributes - - A new compound data type is defined for encoding file attributes. - The same encoding is used both when returning file attributes from - the server and when sending file attributes to the server. When - sending it to the server, the flags field specifies which attributes - are included, and the server will use default values for the - remaining attributes (or will not modify the values of remaining - attributes). When receiving attributes from the server, the flags - specify which attributes are included in the returned data. The - server normally returns all attributes it knows about. - - uint32 flags - byte type always present - uint64 size present only if flag SSH_FILEXFER_ATTR_SIZE - string owner present only if flag SSH_FILEXFER_ATTR_OWNERGROUP - string group present only if flag SSH_FILEXFER_ATTR_OWNERGROUP - uint32 permissions present only if flag SSH_FILEXFER_ATTR_PERMISSIONS - uint32 atime present only if flag SSH_FILEXFER_ATTR_ACCESSTIME - uint32 createtime present only if flag SSH_FILEXFER_ATTR_CREATETIME - uint32 mtime present only if flag SSH_FILEXFER_ATTR_MODIFYTIME - string acl present only if flag SSH_FILEXFER_ATTR_ACL - uint32 extended_count present only if flag SSH_FILEXFER_ATTR_EXTENDED - string extended_type - string extended_data - ... more extended data (extended_type - extended_data pairs), - so that number of pairs equals extended_count - - -5.1 Flags - - The `flags' specify which of the fields are present. Those fields - for which the corresponding flag is not set are not present (not - included in the packet). New flags can only be added by incrementing - the protocol version number (or by using the extension mechanism - described below). - - The flags bits are defined to have the following values: - - #define SSH_FILEXFER_ATTR_SIZE 0x00000001 - #define SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004 - #define SSH_FILEXFER_ATTR_ACCESSTIME 0x00000008 - #define SSH_FILEXFER_ATTR_CREATETIME 0x00000010 - #define SSH_FILEXFER_ATTR_MODIFYTIME 0x00000020 - #define SSH_FILEXFER_ATTR_ACL 0x00000040 - #define SSH_FILEXFER_ATTR_OWNERGROUP 0x00000080 - #define SSH_FILEXFER_ATTR_EXTENDED 0x80000000 - - - - -Galbraith, et al. Expires April 16, 2003 [Page 9] - -Internet-Draft SSH File Transfer Protocol October 2002 - - - In previous versions of this protocol flags value 0x00000002 was - SSH_FILEXFER_ATTR_UIDGID. This value is now unused, and OWNERGROUP - was given a new value in order to ease implementation burden. - 0x00000002 MUST NOT appear in the mask. Some future version of this - protocol may reuse flag 0x00000002. - -5.2 Type - - The type field is always present. The following types are defined: - - #define SSH_FILEXFER_TYPE_REGULAR 1 - #define SSH_FILEXFER_TYPE_DIRECTORY 2 - #define SSH_FILEXFER_TYPE_SYMLINK 3 - #define SSH_FILEXFER_TYPE_SPECIAL 4 - #define SSH_FILEXFER_TYPE_UNKNOWN 5 - - On a POSIX system, these values would be derived from the permission - field. - -5.3 Size - - The `size' field specifies the size of the file on disk, in bytes. - If it is present during file creation, it should be considered a hint - as to the files eventual size. - - Files opened with the SSH_FXF_TEXT flag may have a size that is - greater or less than the value of the size field. - -5.4 Owner and Group - - The `owner' and `group' fields are represented as UTF-8 strings; this - is the form used by NFS v4. See NFS version 4 Protocol. [3] The - following text is selected quotations from section 5.6. - - To avoid a representation that is tied to a particular underlying - implementation at the client or server, the use of UTF-8 strings has - been chosen. The string should be of the form user@dns_domain". - This will allow for a client and server that do not use the same - local representation the ability to translate to a common syntax that - can be interpreted by both. In the case where there is no - translation available to the client or server, the attribute value - must be constructed without the "@". Therefore, the absence of the @ - from the owner or owner_group attribute signifies that no translation - was available and the receiver of the attribute should not place any - special meaning with the attribute value. Even though the attribute - value can not be translated, it may still be useful. In the case of - a client, the attribute string may be used for local display of - ownership. - - - -Galbraith, et al. Expires April 16, 2003 [Page 10] - -Internet-Draft SSH File Transfer Protocol October 2002 - - -5.5 Permissions - - The `permissions' field contains a bit mask of file permissions as - defined by POSIX [1]. - -5.6 Times - - The 'atime', 'createtime', and 'mtime' contain the access, creation, - and modification times of the files, respectively. They are - represented as seconds from Jan 1, 1970 in UTC. - -5.7 ACL - - The 'ACL' field contains an ACL similar to that defined in section - 5.9 of NFS version 4 Protocol [3]. - - uint32 ace-count - - repeated ace-count time: - uint32 ace-type - uint32 ace-flag - uint32 ace-mask - string who [UTF-8] - - ace-type is one of the following four values (taken from NFS Version - 4 Protocol [3]: - - const ACE4_ACCESS_ALLOWED_ACE_TYPE = 0x00000000; - const ACE4_ACCESS_DENIED_ACE_TYPE = 0x00000001; - const ACE4_SYSTEM_AUDIT_ACE_TYPE = 0x00000002; - const ACE4_SYSTEM_ALARM_ACE_TYPE = 0x00000003; - - ace-flag is a combination of the following flag values. See NFS - Version 4 Protocol [3] section 5.9.2: - - const ACE4_FILE_INHERIT_ACE = 0x00000001; - const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002; - const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004; - const ACE4_INHERIT_ONLY_ACE = 0x00000008; - const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010; - const ACE4_FAILED_ACCESS_ACE_FLAG = 0x00000020; - const ACE4_IDENTIFIER_GROUP = 0x00000040; - - ace-mask is any combination of the following flags (taken from NFS - Version 4 Protocol [3] section 5.9.3: - - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 11] - -Internet-Draft SSH File Transfer Protocol October 2002 - - - const ACE4_READ_DATA = 0x00000001; - const ACE4_LIST_DIRECTORY = 0x00000001; - const ACE4_WRITE_DATA = 0x00000002; - const ACE4_ADD_FILE = 0x00000002; - const ACE4_APPEND_DATA = 0x00000004; - const ACE4_ADD_SUBDIRECTORY = 0x00000004; - const ACE4_READ_NAMED_ATTRS = 0x00000008; - const ACE4_WRITE_NAMED_ATTRS = 0x00000010; - const ACE4_EXECUTE = 0x00000020; - const ACE4_DELETE_CHILD = 0x00000040; - const ACE4_READ_ATTRIBUTES = 0x00000080; - const ACE4_WRITE_ATTRIBUTES = 0x00000100; - const ACE4_DELETE = 0x00010000; - const ACE4_READ_ACL = 0x00020000; - const ACE4_WRITE_ACL = 0x00040000; - const ACE4_WRITE_OWNER = 0x00080000; - const ACE4_SYNCHRONIZE = 0x00100000; - - who is a UTF-8 string of the form described in 'Owner and Group' - (Section 5.4) - -5.8 Extended attributes - - The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension - mechanism for vendor-specific extensions. If the flag is specified, - then the `extended_count' field is present. It specifies the number - of extended_type-extended_data pairs that follow. Each of these - pairs specifies an extended attribute. For each of the attributes, - the extended_type field should be a string of the format - "name@domain", where "domain" is a valid, registered domain name and - "name" identifies the method. The IETF may later standardize certain - names that deviate from this format (e.g., that do not contain the - "@" sign). The interpretation of `extended_data' depends on the - type. Implementations SHOULD ignore extended data fields that they - do not understand. - - Additional fields can be added to the attributes by either defining - additional bits to the flags field to indicate their presence, or by - defining extended attributes for them. The extended attributes - mechanism is recommended for most purposes; additional flags bits - should only be defined by an IETF standards action that also - increments the protocol version number. The use of such new fields - MUST be negotiated by the version number in the protocol exchange. - It is a protocol error if a packet with unsupported protocol bits is - received. - - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 12] - -Internet-Draft SSH File Transfer Protocol October 2002 - - -6. Requests From the Client to the Server - - Requests from the client to the server represent the various file - system operations. Each request begins with an `id' field, which is - a 32-bit identifier identifying the request (selected by the client). - The same identifier will be returned in the response to the request. - One possible implementation is a monotonically increasing request - sequence number (modulo 2^32). - - Many operations in the protocol operate on open files. The - SSH_FXP_OPEN request can return a file handle (which is an opaque - variable-length string) which may be used to access the file later - (e.g. in a read operation). The client MUST NOT send requests the - server with bogus or closed handles. However, the server MUST - perform adequate checks on the handle in order to avoid security - risks due to fabricated handles. - - This design allows either stateful and stateless server - implementation, as well as an implementation which caches state - between requests but may also flush it. The contents of the file - handle string are entirely up to the server and its design. The - client should not modify or attempt to interpret the file handle - strings. - - The file handle strings MUST NOT be longer than 256 bytes. - -6.1 Request Synchronization and Reordering - - The protocol and implementations MUST process requests relating to - the same file in the order in which they are received. In other - words, if an application submits multiple requests to the server, the - results in the responses will be the same as if it had sent the - requests one at a time and waited for the response in each case. For - example, the server may process non-overlapping read/write requests - to the same file in parallel, but overlapping reads and writes cannot - be reordered or parallelized. However, there are no ordering - restrictions on the server for processing requests from two different - file transfer connections. The server may interleave and parallelize - them at will. - - There are no restrictions on the order in which responses to - outstanding requests are delivered to the client, except that the - server must ensure fairness in the sense that processing of no - request will be indefinitely delayed even if the client is sending - other requests so that there are multiple outstanding requests all - the time. - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 13] - -Internet-Draft SSH File Transfer Protocol October 2002 - - -6.2 File Names - - This protocol represents file names as strings. File names are - assumed to use the slash ('/') character as a directory separator. - - File names starting with a slash are "absolute", and are relative to - the root of the file system. Names starting with any other character - are relative to the user's default directory (home directory). Note - that identifying the user is assumed to take place outside of this - protocol. - - Servers SHOULD interpret a path name component ".." as referring to - the parent directory, and "." as referring to the current directory. - If the server implementation limits access to certain parts of the - file system, it must be extra careful in parsing file names when - enforcing such restrictions. There have been numerous reported - security bugs where a ".." in a path name has allowed access outside - the intended area. - - An empty path name is valid, and it refers to the user's default - directory (usually the user's home directory). - - Otherwise, no syntax is defined for file names by this specification. - Clients should not make any other assumptions; however, they can - splice path name components returned by SSH_FXP_READDIR together - using a slash ('/') as the separator, and that will work as expected. - - In order to comply with IETF Policy on Character Sets and Languages - [2], all filenames are to be encoded in UTF-8. The shortest valid - UTF-8 encoding of the UNICODE data MUST be used. The server is - responsible for converting the UNICODE data to whatever canonical - form it requires. - - For example, if the server requires that precomposed characters - always be used, the server MUST NOT assume the filename as sent by - the client has this attribute, but must do this normalization itself. - - It is understood that the lack of well-defined semantics for file - names may cause interoperability problems between clients and servers - using radically different operating systems. However, this approach - is known to work acceptably with most systems, and alternative - approaches that e.g. treat file names as sequences of structured - components are quite complicated. - -6.3 Opening, Creating, and Closing Files - - Files are opened and created using the SSH_FXP_OPEN message, whose - data part is as follows: - - - -Galbraith, et al. Expires April 16, 2003 [Page 14] - -Internet-Draft SSH File Transfer Protocol October 2002 - - - uint32 id - string filename [UTF-8] - uint32 pflags - ATTRS attrs - - The `id' field is the request identifier as for all requests. - - The `filename' field specifies the file name. See Section ``File - Names'' for more information. - - The `pflags' field is a bitmask. The following bits have been - defined. - - #define SSH_FXF_READ 0x00000001 - #define SSH_FXF_WRITE 0x00000002 - #define SSH_FXF_APPEND 0x00000004 - #define SSH_FXF_CREAT 0x00000008 - #define SSH_FXF_TRUNC 0x00000010 - #define SSH_FXF_EXCL 0x00000020 - #define SSH_FXF_TEXT 0x00000040 - - These have the following meanings: - - SSH_FXF_READ - Open the file for reading. - - SSH_FXF_WRITE - Open the file for writing. If both this and SSH_FXF_READ are - specified, the file is opened for both reading and writing. - - SSH_FXF_APPEND - Force all writes to append data at the end of the file. The - offset parameter to write will be ignored. - - SSH_FXF_CREAT - If this flag is specified, then a new file will be created if one - does not already exist (if O_TRUNC is specified, the new file will - be truncated to zero length if it previously exists). - - SSH_FXF_TRUNC - Forces an existing file with the same name to be truncated to zero - length when creating a file by specifying SSH_FXF_CREAT. - SSH_FXF_CREAT MUST also be specified if this flag is used. - - SSH_FXF_EXCL - Causes the request to fail if the named file already exists. - SSH_FXF_CREAT MUST also be specified if this flag is used. - - - - -Galbraith, et al. Expires April 16, 2003 [Page 15] - -Internet-Draft SSH File Transfer Protocol October 2002 - - - SSH_FXF_TEXT - Indicates that the server should treat the file as text and - convert it to the canonical newline convention in use. (See - Determining Server Newline Convention. (Section 4.3) - - When a file is opened with the FXF_TEXT flag, the offset field in - both the read and write function are ignored. - - Servers MUST correctly process multiple parallel reads and writes - correctly in this mode. Naturally, it is permissible for them to - do this by serializing the requests. It would not be possible for - a client to reliably detect a server that does not implement - parallel writes in time to prevent damage. - - Clients SHOULD use the SSH_FXF_APPEND flag to append data to a - text file rather then using write with a calculated offset. - - To support seeks on text file the following SSH_FXP_EXTENDED - packet is defined. - - - - string "text-seek" - string file-handle - uint64 line-number - - line-number is the index of the line number to seek to, where byte - 0 in the file is line number 0, and the byte directly following - the first newline sequence in the file is line number 1 and so on. - - The response to a "text-seek" request is an SSH_FXP_STATUS - message. - - An attempt to seek past the end-of-file should result in a - SSH_FX_EOF status. - - Servers SHOULD support at least one "text-seek" in order to - support resume. However, a client MUST be prepared to receive - SSH_FX_OP_UNSUPPORTED when attempting a "text-seek" operation. - The client can then try a fall-back strategy, if it has one. - - Clients MUST be prepared to handle SSH_FX_OP_UNSUPPORTED returned - for read or write operations that are not sequential. - - The `attrs' field specifies the initial attributes for the file. - Default values will be used for those attributes that are not - specified. See Section ``File Attributes'' for more information. - - - - -Galbraith, et al. Expires April 16, 2003 [Page 16] - -Internet-Draft SSH File Transfer Protocol October 2002 - - - The response to this message will be either SSH_FXP_HANDLE (if the - operation is successful) or SSH_FXP_STATUS (if the operation fails). - - A file is closed by using the SSH_FXP_CLOSE request. Its data field - has the following format: - - uint32 id - string handle - - where `id' is the request identifier, and `handle' is a handle - previously returned in the response to SSH_FXP_OPEN or - SSH_FXP_OPENDIR. The handle becomes invalid immediately after this - request has been sent. - - The response to this request will be a SSH_FXP_STATUS message. One - should note that on some server platforms even a close can fail. - This can happen e.g. if the server operating system caches writes, - and an error occurs while flushing cached writes during the close. - -6.4 Reading and Writing - - Once a file has been opened, it can be read using the SSH_FXP_READ - message, which has the following format: - - uint32 id - string handle - uint64 offset - uint32 len - - where `id' is the request identifier, `handle' is an open file handle - returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) relative - to the beginning of the file from where to start reading, and `len' - is the maximum number of bytes to read. - - In response to this request, the server will read as many bytes as it - can from the file (up to `len'), and return them in a SSH_FXP_DATA - message. If an error occurs or EOF is encountered before reading any - data, the server will respond with SSH_FXP_STATUS. For normal disk - files, it is guaranteed that this will read the specified number of - bytes, or up to end of file. For e.g. device files this may return - fewer bytes than requested. - - Writing to a file is achieved using the SSH_FXP_WRITE message, which - has the following format: - - - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 17] - -Internet-Draft SSH File Transfer Protocol October 2002 - - - uint32 id - string handle - uint64 offset - string data - - where `id' is a request identifier, `handle' is a file handle - returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) from the - beginning of the file where to start writing, and `data' is the data - to be written. - - The write will extend the file if writing beyond the end of the file. - It is legal to write way beyond the end of the file; the semantics - are to write zeroes from the end of the file to the specified offset - and then the data. On most operating systems, such writes do not - allocate disk space but instead leave "holes" in the file. - - The server responds to a write request with a SSH_FXP_STATUS message. - -6.5 Removing and Renaming Files - - Files can be removed using the SSH_FXP_REMOVE message. It has the - following format: - - uint32 id - string filename [UTF-8] - - where `id' is the request identifier and `filename' is the name of - the file to be removed. See Section ``File Names'' for more - information. This request cannot be used to remove directories. - - The server will respond to this request with a SSH_FXP_STATUS - message. - - Files (and directories) can be renamed using the SSH_FXP_RENAME - message. Its data is as follows: - - uint32 id - string oldpath [UTF-8] - string newpath [UTF-8] - - where `id' is the request identifier, `oldpath' is the name of an - existing file or directory, and `newpath' is the new name for the - file or directory. It is an error if there already exists a file - with the name specified by newpath. The server may also fail rename - requests in other situations, for example if `oldpath' and `newpath' - point to different file systems on the server. - - The server will respond to this request with a SSH_FXP_STATUS - - - -Galbraith, et al. Expires April 16, 2003 [Page 18] - -Internet-Draft SSH File Transfer Protocol October 2002 - - - message. - -6.6 Creating and Deleting Directories - - New directories can be created using the SSH_FXP_MKDIR request. It - has the following format: - - uint32 id - string path [UTF-8] - ATTRS attrs - - where `id' is the request identifier. - - `path' specifies the directory to be created. See Section ``File - Names'' for more information on file names. - - `attrs' specifies the attributes that should be applied to it upon - creation. Attributes are discussed in more detail in Section ``File - Attributes''. - - The server will respond to this request with a SSH_FXP_STATUS - message. If a file or directory with the specified path already - exists, an error will be returned. - - Directories can be removed using the SSH_FXP_RMDIR request, which has - the following format: - - uint32 id - string path [UTF-8] - - where `id' is the request identifier, and `path' specifies the - directory to be removed. See Section ``File Names'' for more - information on file names. - - The server responds to this request with a SSH_FXP_STATUS message. - Errors may be returned from this operation for various reasons, - including, but not limited to, the path does not exist, the path does - not refer to a directory object, the directory is not empty, or the - user has insufficient access or permission to perform the requested - operation. - -6.7 Scanning Directories - - The files in a directory can be listed using the SSH_FXP_OPENDIR and - SSH_FXP_READDIR requests. Each SSH_FXP_READDIR request returns one - or more file names with full file attributes for each file. The - client should call SSH_FXP_READDIR repeatedly until it has found the - file it is looking for or until the server responds with a - - - -Galbraith, et al. Expires April 16, 2003 [Page 19] - -Internet-Draft SSH File Transfer Protocol October 2002 - - - SSH_FXP_STATUS message indicating an error (normally SSH_FX_EOF if - there are no more files in the directory). The client should then - close the handle using the SSH_FXP_CLOSE request. - - The SSH_FXP_OPENDIR opens a directory for reading. It has the - following format: - - uint32 id - string path [UTF-8] - - where `id' is the request identifier and `path' is the path name of - the directory to be listed (without any trailing slash). See Section - ``File Names'' for more information on file names. This will return - an error if the path does not specify a directory or if the directory - is not readable. The server will respond to this request with either - a SSH_FXP_HANDLE or a SSH_FXP_STATUS message. - - Once the directory has been successfully opened, files (and - directories) contained in it can be listed using SSH_FXP_READDIR - requests. These are of the format - - uint32 id - string handle - - where `id' is the request identifier, and `handle' is a handle - returned by SSH_FXP_OPENDIR. (It is a protocol error to attempt to - use an ordinary file handle returned by SSH_FXP_OPEN.) - - The server responds to this request with either a SSH_FXP_NAME or a - SSH_FXP_STATUS message. One or more names may be returned at a time. - Full status information is returned for each name in order to speed - up typical directory listings. - - If there are no more names available to be read, the server MUST - respond with a SSH_FXP_STATUS message with error code of SSH_FX_EOF. - - When the client no longer wishes to read more names from the - directory, it SHOULD call SSH_FXP_CLOSE for the handle. The handle - should be closed regardless of whether an error has occurred or not. - -6.8 Retrieving File Attributes - - Very often, file attributes are automatically returned by - SSH_FXP_READDIR. However, sometimes there is need to specifically - retrieve the attributes for a named file. This can be done using the - SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests. - - SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT - - - -Galbraith, et al. Expires April 16, 2003 [Page 20] - -Internet-Draft SSH File Transfer Protocol October 2002 - - - follows symbolic links on the server, whereas SSH_FXP_LSTAT does not - follow symbolic links. Both have the same format: - - uint32 id - string path [UTF-8] - uint32 flags - - where `id' is the request identifier, and `path' specifies the file - system object for which status is to be returned. The server - responds to this request with either SSH_FXP_ATTRS or SSH_FXP_STATUS. - - The flags field specify the attribute flags in which the client has - particular interest. This is a hint to the server. For example, - because retrieving owner / group and acl information can be an - expensive operation under some operating systems, the server may - choose not to retrieve this information unless the client expresses a - specific interest in it. - - The client has no guarantee the server will provide all the fields - that it has expressed an interest in. - - SSH_FXP_FSTAT differs from the others in that it returns status - information for an open file (identified by the file handle). Its - format is as follows: - - uint32 id - string handle - uint32 flags - - where `id' is the request identifier and `handle' is a file handle - returned by SSH_FXP_OPEN. The server responds to this request with - SSH_FXP_ATTRS or SSH_FXP_STATUS. - -6.9 Setting File Attributes - - File attributes may be modified using the SSH_FXP_SETSTAT and - SSH_FXP_FSETSTAT requests. These requests are used for operations - such as changing the ownership, permissions or access times, as well - as for truncating a file. - - The SSH_FXP_SETSTAT request is of the following format: - - uint32 id - string path [UTF-8] - ATTRS attrs - - where `id' is the request identifier, `path' specifies the file - system object (e.g. file or directory) whose attributes are to be - - - -Galbraith, et al. Expires April 16, 2003 [Page 21] - -Internet-Draft SSH File Transfer Protocol October 2002 - - - modified, and `attrs' specifies the modifications to be made to its - attributes. Attributes are discussed in more detail in Section - ``File Attributes''. - - An error will be returned if the specified file system object does - not exist or the user does not have sufficient rights to modify the - specified attributes. The server responds to this request with a - SSH_FXP_STATUS message. - - The SSH_FXP_FSETSTAT request modifies the attributes of a file which - is already open. It has the following format: - - uint32 id - string handle - ATTRS attrs - - where `id' is the request identifier, `handle' (MUST be returned by - SSH_FXP_OPEN) identifies the file whose attributes are to be - modified, and `attrs' specifies the modifications to be made to its - attributes. Attributes are discussed in more detail in Section - ``File Attributes''. The server will respond to this request with - SSH_FXP_STATUS. - -6.10 Dealing with Symbolic links - - The SSH_FXP_READLINK request may be used to read the target of a - symbolic link. It would have a data part as follows: - - uint32 id - string path [UTF-8] - - where `id' is the request identifier and `path' specifies the path - name of the symlink to be read. - - The server will respond with a SSH_FXP_NAME packet containing only - one name and a dummy attributes value. The name in the returned - packet contains the target of the link. If an error occurs, the - server may respond with SSH_FXP_STATUS. - - The SSH_FXP_SYMLINK request will create a symbolic link on the - server. It is of the following format - - uint32 id - string linkpath [UTF-8] - string targetpath [UTF-8] - - where `id' is the request identifier, `linkpath' specifies the path - name of the symlink to be created and `targetpath' specifies the - - - -Galbraith, et al. Expires April 16, 2003 [Page 22] - -Internet-Draft SSH File Transfer Protocol October 2002 - - - target of the symlink. The server shall respond with a - SSH_FXP_STATUS indicating either success (SSH_FX_OK) or an error - condition. - -6.11 Canonicalizing the Server-Side Path Name - - The SSH_FXP_REALPATH request can be used to have the server - canonicalize any given path name to an absolute path. This is useful - for converting path names containing ".." components or relative - pathnames without a leading slash into absolute paths. The format of - the request is as follows: - - uint32 id - string path [UTF-8] - - where `id' is the request identifier and `path' specifies the path - name to be canonicalized. The server will respond with a - SSH_FXP_NAME packet containing the name in canonical form and a dummy - attributes value. If an error occurs, the server may also respond - with SSH_FXP_STATUS. - -6.11.1 Best practice for dealing with paths - - The client SHOULD treat the results of SSH_FXP_REALPATH as a - canonical absolute path, even if the path does not appear to be - absolute. A client that use REALPATH(".") and treats the result as - absolute, even if there is no leading slash, will continue to - function correctly, even when talking to a Windows NT or VMS style - system, where absolute paths may not begin with a slash. - - For example, if the client wishes to change directory up, and the - server has returned "c:/x/y/z" from REALPATH, the client SHOULD use - "c:/x/y/z/..". - - As a second example, if the client wishes to open the file "x.txt" in - the current directory, and server has returned "dka100:/x/y/z" as the - canonical path of the directory, the client SHOULD open "dka100:/x/y/ - z/x.txt" - - - - - - - - - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 23] - -Internet-Draft SSH File Transfer Protocol October 2002 - - -7. Responses from the Server to the Client - - The server responds to the client using one of a few response - packets. All requests can return a SSH_FXP_STATUS response upon - failure. When the operation is successful, any of the responses may - be returned (depending on the operation). If no data needs to be - returned to the client, the SSH_FXP_STATUS response with SSH_FX_OK - status is appropriate. Otherwise, the SSH_FXP_HANDLE message is used - to return a file handle (for SSH_FXP_OPEN and SSH_FXP_OPENDIR - requests), SSH_FXP_DATA is used to return data from SSH_FXP_READ, - SSH_FXP_NAME is used to return one or more file names from a - SSH_FXP_READDIR or SSH_FXP_REALPATH request, and SSH_FXP_ATTRS is - used to return file attributes from SSH_FXP_STAT, SSH_FXP_LSTAT, and - SSH_FXP_FSTAT requests. - - Exactly one response will be returned for each request. Each - response packet contains a request identifier which can be used to - match each response with the corresponding request. Note that it is - legal to have several requests outstanding simultaneously, and the - server is allowed to send responses to them in a different order from - the order in which the requests were sent (the result of their - execution, however, is guaranteed to be as if they had been processed - one at a time in the order in which the requests were sent). - - Response packets are of the same general format as request packets. - Each response packet begins with the request identifier. - - The format of the data portion of the SSH_FXP_STATUS response is as - follows: - - uint32 id - uint32 error/status code - string error message (ISO-10646 UTF-8 [RFC-2279]) - string language tag (as defined in [RFC-1766]) - - where `id' is the request identifier, and `error/status code' - indicates the result of the requested operation. The value SSH_FX_OK - indicates success, and all other values indicate failure. - - Currently, the following values are defined (other values may be - defined by future versions of this protocol): - - - - - - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 24] - -Internet-Draft SSH File Transfer Protocol October 2002 - - - #define SSH_FX_OK 0 - #define SSH_FX_EOF 1 - #define SSH_FX_NO_SUCH_FILE 2 - #define SSH_FX_PERMISSION_DENIED 3 - #define SSH_FX_FAILURE 4 - #define SSH_FX_BAD_MESSAGE 5 - #define SSH_FX_NO_CONNECTION 6 - #define SSH_FX_CONNECTION_LOST 7 - #define SSH_FX_OP_UNSUPPORTED 8 - #define SSH_FX_INVALID_HANDLE 9 - #define SSH_FX_NO_SUCH_PATH 10 - #define SSH_FX_FILE_ALREADY_EXISTS 11 - #define SSH_FX_WRITE_PROTECT 12 - - SSH_FX_OK - Indicates successful completion of the operation. - - SSH_FX_EOF - indicates end-of-file condition; for SSH_FX_READ it means that no - more data is available in the file, and for SSH_FX_READDIR it - indicates that no more files are contained in the directory. - - SSH_FX_NO_SUCH_FILE - is returned when a reference is made to a file which does not - exist. - - SSH_FX_PERMISSION_DENIED - is returned when the authenticated user does not have sufficient - permissions to perform the operation. - - SSH_FX_FAILURE - is a generic catch-all error message; it should be returned if an - error occurs for which there is no more specific error code - defined. - - SSH_FX_BAD_MESSAGE - may be returned if a badly formatted packet or protocol - incompatibility is detected. - - SSH_FX_NO_CONNECTION - is a pseudo-error which indicates that the client has no - connection to the server (it can only be generated locally by the - client, and MUST NOT be returned by servers). - - SSH_FX_CONNECTION_LOST - is a pseudo-error which indicates that the connection to the - server has been lost (it can only be generated locally by the - client, and MUST NOT be returned by servers). - - - -Galbraith, et al. Expires April 16, 2003 [Page 25] - -Internet-Draft SSH File Transfer Protocol October 2002 - - - SSH_FX_OP_UNSUPPORTED - indicates that an attempt was made to perform an operation which - is not supported for the server (it may be generated locally by - the client if e.g. the version number exchange indicates that a - required feature is not supported by the server, or it may be - returned by the server if the server does not implement an - operation). - - SSH_FX_INVALID_HANDLE - The handle value was invalid. - - SSH_FX_NO_SUCH_PATH - The file path does not exist or is invalid. - - SSH_FX_FILE_ALREADY_EXISTS - The file already exists. - - SSH_FX_WRITE_PROTECT - The file is on read only media, or the media is write protected. - - The SSH_FXP_HANDLE response has the following format: - - uint32 id - string handle - - where `id' is the request identifier, and `handle' is an arbitrary - string that identifies an open file or directory on the server. The - handle is opaque to the client; the client MUST NOT attempt to - interpret or modify it in any way. The length of the handle string - MUST NOT exceed 256 data bytes. - - The SSH_FXP_DATA response has the following format: - - uint32 id - string data - - where `id' is the request identifier, and `data' is an arbitrary byte - string containing the requested data. The data string may be at most - the number of bytes requested in a SSH_FXP_READ request, but may also - be shorter if end of file is reached or if the read is from something - other than a regular file. - - The SSH_FXP_NAME response has the following format: - - - - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 26] - -Internet-Draft SSH File Transfer Protocol October 2002 - - - uint32 id - uint32 count - repeats count times: - string filename [UTF-8] - ATTRS attrs - - where `id' is the request identifier, `count' is the number of names - returned in this response, and the remaining fields repeat `count' - times (so that all three fields are first included for the first - file, then for the second file, etc). In the repeated part, - `filename' is a file name being returned (for SSH_FXP_READDIR, it - will be a relative name within the directory, without any path - components; for SSH_FXP_REALPATH it will be an absolute path name), - and `attrs' is the attributes of the file as described in Section - ``File Attributes''. - - The SSH_FXP_ATTRS response has the following format: - - uint32 id - ATTRS attrs - - where `id' is the request identifier, and `attrs' is the returned - file attributes as described in Section ``File Attributes''. - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 27] - -Internet-Draft SSH File Transfer Protocol October 2002 - - -8. Vendor-Specific Extensions - - The SSH_FXP_EXTENDED request provides a generic extension mechanism - for adding vendor-specific commands. The request has the following - format: - - uint32 id - string extended-request - ... any request-specific data ... - - where `id' is the request identifier, and `extended-request' is a - string of the format "name@domain", where domain is an internet - domain name of the vendor defining the request. The rest of the - request is completely vendor-specific, and servers should only - attempt to interpret it if they recognize the `extended-request' - name. - - The server may respond to such requests using any of the response - packets defined in Section ``Responses from the Server to the - Client''. Additionally, the server may also respond with a - SSH_FXP_EXTENDED_REPLY packet, as defined below. If the server does - not recognize the `extended-request' name, then the server MUST - respond with SSH_FXP_STATUS with error/status set to - SSH_FX_OP_UNSUPPORTED. - - The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary - extension-specific data from the server to the client. It is of the - following format: - - uint32 id - ... any request-specific data ... - - There is a range of packet types reserved for use by extensions. In - order to avoid collision, extensions that turn on the use of - additional packet types should determine those numbers dynamically. - - The suggested way of doing this is have an extension request from the - client to the server that enables the extension; the extension - response from the server to the client would specify the actual type - values to use, in additional to any other data. - - Extension authors should be mindful of the limited range of packet - types available (there are only 45 values available) and avoid - requiring a new packet type where possible. - - - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 28] - -Internet-Draft SSH File Transfer Protocol October 2002 - - -9. Security Considerations - - This protocol assumes that it is run over a secure channel and that - the endpoints of the channel have been authenticated. Thus, this - protocol assumes that it is externally protected from network-level - attacks. - - This protocol provides file system access to arbitrary files on the - server (only constrained by the server implementation). It is the - responsibility of the server implementation to enforce any access - controls that may be required to limit the access allowed for any - particular user (the user being authenticated externally to this - protocol, typically using the SSH User Authentication Protocol [8]. - - Care must be taken in the server implementation to check the validity - of received file handle strings. The server should not rely on them - directly; it MUST check the validity of each handle before relying on - it. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 29] - -Internet-Draft SSH File Transfer Protocol October 2002 - - -10. Changes from previous protocol versions - - The SSH File Transfer Protocol has changed over time, before it's - standardization. The following is a description of the incompatible - changes between different versions. - -10.1 Changes between versions 4 and 3 - - Many of the changes between version 4 and version 3 are to the - attribute structure to make it more flexible for non-unix platforms. - - o Make all filenames UTF-8. - - o Added 'newline' extension. - - o Made file attribute owner and group strings so they can actually - be used on disparate systems. - - o Added createtime field, and added separate flags for atime, - createtime, and mtime so they can be set separately. - - o Split the file type out of the permissions field and into it's own - field (which is always present.) - - o Added acl attribute. - - o Added SSH_FXF_TEXT file open flag. - - o Added flags field to the get stat commands so that the client can - specifically request information the server might not normally - included for performance reasons. - - o Removed the long filename from the names structure-- it can now be - built from information available in the attrs structure. - - o Added reserved range of packet numbers for extensions. - - o Added several additional error codes. - - o Change the way version negotiate works slightly. Previously, if - the client version were higher than the server version, the server - was supposed to 'echo back' the clients version. The server now - sends it's own version and the lower of the two is considered to - be the one in use. - - - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 30] - -Internet-Draft SSH File Transfer Protocol October 2002 - - -10.2 Changes between versions 3 and 2 - - o The SSH_FXP_READLINK and SSH_FXP_SYMLINK messages were added. - - o The SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY messages were - added. - - o The SSH_FXP_STATUS message was changed to include fields `error - message' and `language tag'. - - -10.3 Changes between versions 2 and 1 - - o The SSH_FXP_RENAME message was added. - - -10.4 Changes between versions 1 and 0 - - o Implementation changes, no actual protocol changes. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 31] - -Internet-Draft SSH File Transfer Protocol October 2002 - - -11. Trademark Issues - - "ssh" is a registered trademark of SSH Communications Security Corp - in the United States and/or other countries. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 32] - -Internet-Draft SSH File Transfer Protocol October 2002 - - -References - - [1] Dierks, T., Allen, C., Treese, W., Karlton, P., Freier, A. and - P. Kocher, "The TLS Protocol Version 1.0", RFC 2246, January - 1999. - - [2] Alvestrand, H., "IETF Policy on Character Sets and Languages", - BCP 18, RFC 2277, January 1998. - - [3] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., Beame, - C., Eisler, M. and D. Noveck, "NFS version 4 Protocol", RFC - 3010, December 2000. - - [4] Institute of Electrical and Electronics Engineers, "Information - Technology - Portable Operating System Interface (POSIX) - Part - 1: System Application Program Interface (API) [C Language]", - IEEE Standard 1003.2, 1996. - - [5] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S. - Lehtinen, "SSH Protocol Architecture", draft-ietf-secsh- - architecture-13 (work in progress), September 2002. - - [6] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S. - Lehtinen, "SSH Protocol Transport Protocol", draft-ietf-secsh- - transport-15 (work in progress), September 2002. - - [7] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S. - Lehtinen, "SSH Connection Protocol", draft-ietf-secsh-connect-16 - (work in progress), September 2002. - - [8] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S. - Lehtinen, "SSH Authentication Protocol", draft-ietf-secsh- - userauth-16 (work in progress), September 2002. - - -Authors' Addresses - - Joseph Galbraith - VanDyke Software - 4848 Tramway Ridge Blvd - Suite 101 - Albuquerque, NM 87111 - US - - Phone: +1 505 332 5700 - EMail: [email protected] - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 33] - -Internet-Draft SSH File Transfer Protocol October 2002 - - - Tatu Ylonen - SSH Communications Security Corp - Fredrikinkatu 42 - HELSINKI FIN-00100 - Finland - - EMail: [email protected] - - - Sami Lehtinen - SSH Communications Security Corp - Fredrikinkatu 42 - HELSINKI FIN-00100 - Finland - - EMail: [email protected] - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 34] - -Internet-Draft SSH File Transfer Protocol October 2002 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2002). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assigns. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS 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. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - - - - - - - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 35] - - diff --git a/lib/ssh/doc/standard/draft-ietf-secsh-filexfer-04.txt b/lib/ssh/doc/standard/draft-ietf-secsh-filexfer-04.txt deleted file mode 100644 index 9f51883cd2..0000000000 --- a/lib/ssh/doc/standard/draft-ietf-secsh-filexfer-04.txt +++ /dev/null @@ -1,2130 +0,0 @@ - - - -Secure Shell Working Group J. Galbraith -Internet-Draft VanDyke Software -Expires: June 18, 2003 T. Ylonen - S. Lehtinen - SSH Communications Security Corp - December 18, 2002 - - - SSH File Transfer Protocol - draft-ietf-secsh-filexfer-04.txt - -Status of this Memo - - This document is an Internet-Draft and is in full conformance with - all provisions of Section 10 of RFC2026. - - Internet-Drafts are working documents of the Internet Engineering - Task Force (IETF), its areas, and its working groups. Note that - other groups may also distribute working documents as - Internet-Drafts. - - Internet-Drafts are draft documents valid for a maximum of six months - and may be updated, replaced, or obsoleted by other documents at any - time. It is inappropriate to use Internet-Drafts as reference - material or to cite them other than as "work in progress." - - The list of current Internet-Drafts can be accessed at http:// - www.ietf.org/ietf/1id-abstracts.txt. - - The list of Internet-Draft Shadow Directories can be accessed at - http://www.ietf.org/shadow.html. - - This Internet-Draft will expire on June 18, 2003. - -Copyright Notice - - Copyright (C) The Internet Society (2002). All Rights Reserved. - -Abstract - - The SSH File Transfer Protocol provides secure file transfer - functionality over any reliable data stream. It is the standard file - transfer protocol for use with the SSH2 protocol. This document - describes the file transfer protocol and its interface to the SSH2 - protocol suite. - - - - - - - -Galbraith, et al. Expires June 18, 2003 [Page 1] - -Internet-Draft SSH File Transfer Protocol December 2002 - - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 3 - 2. Use with the SSH Connection Protocol . . . . . . . . . . . 4 - 3. General Packet Format . . . . . . . . . . . . . . . . . . 5 - 3.1 The use of stderr in the server . . . . . . . . . . . . . 6 - 4. Protocol Initialization . . . . . . . . . . . . . . . . . 8 - 4.1 Client Initialization . . . . . . . . . . . . . . . . . . 8 - 4.2 Server Initialization . . . . . . . . . . . . . . . . . . 8 - 4.3 Determining Server Newline Convention . . . . . . . . . . 9 - 5. File Attributes . . . . . . . . . . . . . . . . . . . . . 10 - 5.1 Flags . . . . . . . . . . . . . . . . . . . . . . . . . . 10 - 5.2 Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 - 5.3 Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 - 5.4 Owner and Group . . . . . . . . . . . . . . . . . . . . . 11 - 5.5 Permissions . . . . . . . . . . . . . . . . . . . . . . . 12 - 5.6 Times . . . . . . . . . . . . . . . . . . . . . . . . . . 12 - 5.7 ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 - 5.8 Extended attributes . . . . . . . . . . . . . . . . . . . 14 - 6. Requests From the Client to the Server . . . . . . . . . . 15 - 6.1 Request Synchronization and Reordering . . . . . . . . . . 15 - 6.2 File Names . . . . . . . . . . . . . . . . . . . . . . . . 16 - 6.3 Opening, Creating, and Closing Files . . . . . . . . . . . 16 - 6.4 Reading and Writing . . . . . . . . . . . . . . . . . . . 19 - 6.5 Removing and Renaming Files . . . . . . . . . . . . . . . 20 - 6.6 Creating and Deleting Directories . . . . . . . . . . . . 21 - 6.7 Scanning Directories . . . . . . . . . . . . . . . . . . . 21 - 6.8 Retrieving File Attributes . . . . . . . . . . . . . . . . 22 - 6.9 Setting File Attributes . . . . . . . . . . . . . . . . . 23 - 6.10 Dealing with Symbolic links . . . . . . . . . . . . . . . 24 - 6.11 Canonicalizing the Server-Side Path Name . . . . . . . . . 25 - 6.11.1 Best practice for dealing with paths . . . . . . . . . . . 25 - 7. Responses from the Server to the Client . . . . . . . . . 26 - 8. Vendor-Specific Extensions . . . . . . . . . . . . . . . . 30 - 9. Security Considerations . . . . . . . . . . . . . . . . . 31 - 10. Changes from previous protocol versions . . . . . . . . . 32 - 10.1 Changes between versions 4 and 3 . . . . . . . . . . . . . 32 - 10.2 Changes between versions 3 and 2 . . . . . . . . . . . . . 33 - 10.3 Changes between versions 2 and 1 . . . . . . . . . . . . . 33 - 10.4 Changes between versions 1 and 0 . . . . . . . . . . . . . 33 - 11. Trademark Issues . . . . . . . . . . . . . . . . . . . . . 34 - References . . . . . . . . . . . . . . . . . . . . . . . . 35 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . 35 - Intellectual Property and Copyright Statements . . . . . . 37 - - - - - - - -Galbraith, et al. Expires June 18, 2003 [Page 2] - -Internet-Draft SSH File Transfer Protocol December 2002 - - -1. Introduction - - This protocol provides secure file transfer (and more generally file - system access) functionality over a reliable data stream, such as a - channel in the SSH2 protocol [5]. - - This protocol is designed so that it could be used to implement a - secure remote file system service, as well as a secure file transfer - service. - - This protocol assumes that it runs over a secure channel, and that - the server has already authenticated the user at the client end, and - that the identity of the client user is externally available to the - server implementation. - - In general, this protocol follows a simple request-response model. - Each request and response contains a sequence number and multiple - requests may be pending simultaneously. There are a relatively large - number of different request messages, but a small number of possible - response messages. Each request has one or more response messages - that may be returned in result (e.g., a read either returns data or - reports error status). - - The packet format descriptions in this specification follow the - notation presented in the secsh architecture draft. [5] - - Even though this protocol is described in the context of the SSH2 - protocol, this protocol is general and independent of the rest of the - SSH2 protocol suite. It could be used in a number of different - applications, such as secure file transfer over TLS RFC 2246 [1] and - transfer of management information in VPN applications. - - - - - - - - - - - - - - - - - - - - -Galbraith, et al. Expires June 18, 2003 [Page 3] - -Internet-Draft SSH File Transfer Protocol December 2002 - - -2. Use with the SSH Connection Protocol - - When used with the SSH2 Protocol suite, this protocol is intended to - be used from the SSH Connection Protocol [7] as a subsystem, as - described in section ``Starting a Shell or a Command''. The - subsystem name used with this protocol is "sftp". - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Galbraith, et al. Expires June 18, 2003 [Page 4] - -Internet-Draft SSH File Transfer Protocol December 2002 - - -3. General Packet Format - - All packets transmitted over the secure connection are of the - following format: - - uint32 length - byte type - byte[length - 1] data payload - - That is, they are just data preceded by 32-bit length and 8-bit type - fields. The `length' is the length of the data area, and does not - include the `length' field itself. The format and interpretation of - the data area depends on the packet type. - - All packet descriptions below only specify the packet type and the - data that goes into the data field. Thus, they should be prefixed by - the `length' and `type' fields. - - The maximum size of a packet is in practice determined by the client - (the maximum size of read or write requests that it sends, plus a few - bytes of packet overhead). All servers SHOULD support packets of at - least 34000 bytes (where the packet size refers to the full length, - including the header above). This should allow for reads and writes - of at most 32768 bytes. - - There is no limit on the number of outstanding (non-acknowledged) - requests that the client may send to the server. In practice this is - limited by the buffering available on the data stream and the queuing - performed by the server. If the server's queues are full, it should - not read any more data from the stream, and flow control will prevent - the client from sending more requests. Note, however, that while - there is no restriction on the protocol level, the client's API may - provide a limit in order to prevent infinite queuing of outgoing - requests at the client. - - The following values are defined for packet types. - - - - - - - - - - - - - - - -Galbraith, et al. Expires June 18, 2003 [Page 5] - -Internet-Draft SSH File Transfer Protocol December 2002 - - - #define SSH_FXP_INIT 1 - #define SSH_FXP_VERSION 2 - #define SSH_FXP_OPEN 3 - #define SSH_FXP_CLOSE 4 - #define SSH_FXP_READ 5 - #define SSH_FXP_WRITE 6 - #define SSH_FXP_LSTAT 7 - #define SSH_FXP_FSTAT 8 - #define SSH_FXP_SETSTAT 9 - #define SSH_FXP_FSETSTAT 10 - #define SSH_FXP_OPENDIR 11 - #define SSH_FXP_READDIR 12 - #define SSH_FXP_REMOVE 13 - #define SSH_FXP_MKDIR 14 - #define SSH_FXP_RMDIR 15 - #define SSH_FXP_REALPATH 16 - #define SSH_FXP_STAT 17 - #define SSH_FXP_RENAME 18 - #define SSH_FXP_READLINK 19 - #define SSH_FXP_SYMLINK 20 - - #define SSH_FXP_STATUS 101 - #define SSH_FXP_HANDLE 102 - #define SSH_FXP_DATA 103 - #define SSH_FXP_NAME 104 - #define SSH_FXP_ATTRS 105 - - #define SSH_FXP_EXTENDED 200 - #define SSH_FXP_EXTENDED_REPLY 201 - - RESERVED_FOR_EXTENSIONS 210-255 - - Additional packet types should only be defined if the protocol - version number (see Section ``Protocol Initialization'') is - incremented, and their use MUST be negotiated using the version - number. However, the SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY - packets can be used to implement vendor-specific extensions. See - Section ``Vendor-Specific-Extensions'' for more details. - -3.1 The use of stderr in the server - - Packets are sent and received on stdout and stdin. Data sent on - stderr by the server SHOULD be considered debug or supplemental error - information, and MAY be displayed to the user. - - For example, during initialization, there is no client request - active, so errors or warning information cannot be sent to the client - as part of the SFTP protocol at this early stage. However, the - - - -Galbraith, et al. Expires June 18, 2003 [Page 6] - -Internet-Draft SSH File Transfer Protocol December 2002 - - - errors or warnings MAY be sent as stderr text. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Galbraith, et al. Expires June 18, 2003 [Page 7] - -Internet-Draft SSH File Transfer Protocol December 2002 - - -4. Protocol Initialization - - When the file transfer protocol starts, the client first sends a - SSH_FXP_INIT (including its version number) packet to the server. - The server responds with a SSH_FXP_VERSION packet, supplying the - lowest of its own and the client's version number. Both parties - should from then on adhere to particular version of the protocol. - - The version number of the protocol specified in this document is 4. - The version number should be incremented for each incompatible - revision of this protocol. - -4.1 Client Initialization - - The SSH_FXP_INIT packet (from client to server) has the following - data: - - uint32 version - - Version 3 of this protocol allowed clients to include extensions in - the SSH_FXP_INIT packet; however, this can cause interoperability - problems with version 1 and version 2 servers because the client must - send this packet before knowing the servers version. - - In this version of the protocol, clients MUST use the - SSH_FXP_EXTENDED packet to send extensions to the server after - version exchange has completed. Clients MUST NOT include extensions - in the version packet. This will prevent interoperability problems - with older servers - -4.2 Server Initialization - - The SSH_FXP_VERSION packet (from server to client) has the following - data: - - uint32 version - <extension data> - - 'version' is the lower of the protocol version supported by the - server and the version number received from the client. - - The extension data may be empty, or may be a sequence of - - string extension_name - string extension_data - - pairs (both strings MUST always be present if one is, but the - `extension_data' string may be of zero length). If present, these - - - -Galbraith, et al. Expires June 18, 2003 [Page 8] - -Internet-Draft SSH File Transfer Protocol December 2002 - - - strings indicate extensions to the baseline protocol. The - `extension_name' field(s) identify the name of the extension. The - name should be of the form "name@domain", where the domain is the DNS - domain name of the organization defining the extension. Additional - names that are not of this format may be defined later by the IETF. - Implementations MUST silently ignore any extensions whose name they - do not recognize. - -4.3 Determining Server Newline Convention - - In order to correctly process text files in a cross platform - compatible way, the newline convention must be converted from that of - the server to that of the client, or, during an upload, from that of - the client to that of the server. - - Versions 3 and prior of this protocol made no provisions for - processing text files. Many clients implemented some sort of - conversion algorithm, but without either a 'canonical' on the wire - format or knowledge of the servers newline convention, correct - conversion was not always possible. - - Starting with Version 4, the SSH_FXF_TEXT file open flag (Section - 6.3) makes it possible to request that the server translate a file to - a 'canonical' on the wire format. This format uses \r\n as the line - separator. - - Servers for systems using multiple newline characters (for example, - Mac OS X or VMS) or systems using counted records, MUST translate to - the canonical form. - - However, to ease the burden of implementation on servers that use a - single, simple separator sequence, the following extension allows the - canonical format to be changed. - - string "newline" - string new-canonical-separator (usually "\r" or "\n" or "\r\n") - - All clients MUST support this extension. - - When processing text files, clients SHOULD NOT translate any - character or sequence that is not an exact match of the servers - newline separator. - - In particular, if the newline sequence being used is the canonical - "\r\n" sequence, a lone \r or a lone \n SHOULD be written through - without change. - - - - - -Galbraith, et al. Expires June 18, 2003 [Page 9] - -Internet-Draft SSH File Transfer Protocol December 2002 - - -5. File Attributes - - A new compound data type is defined for encoding file attributes. - The same encoding is used both when returning file attributes from - the server and when sending file attributes to the server. When - sending it to the server, the flags field specifies which attributes - are included, and the server will use default values for the - remaining attributes (or will not modify the values of remaining - attributes). When receiving attributes from the server, the flags - specify which attributes are included in the returned data. The - server normally returns all attributes it knows about. - - uint32 flags - byte type always present - uint64 size present only if flag SIZE - string owner present only if flag OWNERGROUP - string group present only if flag OWNERGROUP - uint32 permissions present only if flag PERMISSIONS - uint64 atime present only if flag ACCESSTIME - uint32 atime_nseconds present only if flag SUBSECOND_TIMES - uint64 createtime present only if flag CREATETIME - uint32 createtime_nseconds present only if flag SUBSECOND_TIMES - uint64 mtime present only if flag MODIFYTIME - uint32 mtime_nseconds present only if flag SUBSECOND_TIMES - string acl present only if flag ACL - uint32 extended_count present only if flag EXTENDED - string extended_type - string extended_data - ... more extended data (extended_type - extended_data pairs), - so that number of pairs equals extended_count - - -5.1 Flags - - The `flags' specify which of the fields are present. Those fields - for which the corresponding flag is not set are not present (not - included in the packet). New flags can only be added by incrementing - the protocol version number (or by using the extension mechanism - described below). - - The flags bits are defined to have the following values: - - - - - - - - - - -Galbraith, et al. Expires June 18, 2003 [Page 10] - -Internet-Draft SSH File Transfer Protocol December 2002 - - - #define SSH_FILEXFER_ATTR_SIZE 0x00000001 - #define SSH_FILEXFER_ATTR_PERMISSIONS 0x00000040 - #define SSH_FILEXFER_ATTR_ACCESSTIME 0x00000008 - #define SSH_FILEXFER_ATTR_CREATETIME 0x00000010 - #define SSH_FILEXFER_ATTR_MODIFYTIME 0x00000020 - #define SSH_FILEXFER_ATTR_ACL 0x00000040 - #define SSH_FILEXFER_ATTR_OWNERGROUP 0x00000080 - #define SSH_FILEXFER_ATTR_SUBSECOND_TIMES 0x00000100 - #define SSH_FILEXFER_ATTR_EXTENDED 0x80000000 - - In previous versions of this protocol flags value 0x00000002 was - SSH_FILEXFER_ATTR_UIDGID. This value is now unused, and OWNERGROUP - was given a new value in order to ease implementation burden. - 0x00000002 MUST NOT appear in the mask. Some future version of this - protocol may reuse flag 0x00000002. - -5.2 Type - - The type field is always present. The following types are defined: - - #define SSH_FILEXFER_TYPE_REGULAR 1 - #define SSH_FILEXFER_TYPE_DIRECTORY 2 - #define SSH_FILEXFER_TYPE_SYMLINK 3 - #define SSH_FILEXFER_TYPE_SPECIAL 4 - #define SSH_FILEXFER_TYPE_UNKNOWN 5 - - On a POSIX system, these values would be derived from the permission - field. - -5.3 Size - - The `size' field specifies the size of the file on disk, in bytes. - If it is present during file creation, it should be considered a hint - as to the files eventual size. - - Files opened with the SSH_FXF_TEXT flag may have a size that is - greater or less than the value of the size field. - -5.4 Owner and Group - - The `owner' and `group' fields are represented as UTF-8 strings; this - is the form used by NFS v4. See NFS version 4 Protocol. [3] The - following text is selected quotations from section 5.6. - - To avoid a representation that is tied to a particular underlying - implementation at the client or server, the use of UTF-8 strings has - been chosen. The string should be of the form user@dns_domain". - This will allow for a client and server that do not use the same - - - -Galbraith, et al. Expires June 18, 2003 [Page 11] - -Internet-Draft SSH File Transfer Protocol December 2002 - - - local representation the ability to translate to a common syntax that - can be interpreted by both. In the case where there is no - translation available to the client or server, the attribute value - must be constructed without the "@". Therefore, the absence of the @ - from the owner or owner_group attribute signifies that no translation - was available and the receiver of the attribute should not place any - special meaning with the attribute value. Even though the attribute - value can not be translated, it may still be useful. In the case of - a client, the attribute string may be used for local display of - ownership. - -5.5 Permissions - - The `permissions' field contains a bit mask of file permissions as - defined by POSIX [1]. - -5.6 Times - - The 'atime', 'createtime', and 'mtime' contain the access, creation, - and modification times of the files, respectively. They are - represented as seconds from Jan 1, 1970 in UTC. - - A negative value indicates number of seconds before Jan 1, 1970. In - both cases, if the SSH_FILEXFER_ATTR_SUBSECOND_TIMES flag is set, the - nseconds field is to be added to the seconds field for the final time - representation. For example, if the time to be represented is - one-half second before 0 hour January 1, 1970, the seconds field - would have a value of negative one (-1) and the nseconds fields would - have a value of one-half second (500000000). Values greater than - 999,999,999 for nseconds are considered invalid. - -5.7 ACL - - The 'ACL' field contains an ACL similar to that defined in section - 5.9 of NFS version 4 Protocol [3]. - - uint32 ace-count - - repeated ace-count time: - uint32 ace-type - uint32 ace-flag - uint32 ace-mask - string who [UTF-8] - - ace-type is one of the following four values (taken from NFS Version - 4 Protocol [3]: - - - - - -Galbraith, et al. Expires June 18, 2003 [Page 12] - -Internet-Draft SSH File Transfer Protocol December 2002 - - - const ACE4_ACCESS_ALLOWED_ACE_TYPE = 0x00000000; - const ACE4_ACCESS_DENIED_ACE_TYPE = 0x00000001; - const ACE4_SYSTEM_AUDIT_ACE_TYPE = 0x00000002; - const ACE4_SYSTEM_ALARM_ACE_TYPE = 0x00000003; - - ace-flag is a combination of the following flag values. See NFS - Version 4 Protocol [3] section 5.9.2: - - const ACE4_FILE_INHERIT_ACE = 0x00000001; - const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002; - const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004; - const ACE4_INHERIT_ONLY_ACE = 0x00000008; - const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010; - const ACE4_FAILED_ACCESS_ACE_FLAG = 0x00000020; - const ACE4_IDENTIFIER_GROUP = 0x00000040; - - ace-mask is any combination of the following flags (taken from NFS - Version 4 Protocol [3] section 5.9.3: - - const ACE4_READ_DATA = 0x00000001; - const ACE4_LIST_DIRECTORY = 0x00000001; - const ACE4_WRITE_DATA = 0x00000002; - const ACE4_ADD_FILE = 0x00000002; - const ACE4_APPEND_DATA = 0x00000004; - const ACE4_ADD_SUBDIRECTORY = 0x00000004; - const ACE4_READ_NAMED_ATTRS = 0x00000008; - const ACE4_WRITE_NAMED_ATTRS = 0x00000010; - const ACE4_EXECUTE = 0x00000020; - const ACE4_DELETE_CHILD = 0x00000040; - const ACE4_READ_ATTRIBUTES = 0x00000080; - const ACE4_WRITE_ATTRIBUTES = 0x00000100; - const ACE4_DELETE = 0x00010000; - const ACE4_READ_ACL = 0x00020000; - const ACE4_WRITE_ACL = 0x00040000; - const ACE4_WRITE_OWNER = 0x00080000; - const ACE4_SYNCHRONIZE = 0x00100000; - - who is a UTF-8 string of the form described in 'Owner and Group' - (Section 5.4) - - Also, as per '5.9.4 ACE who' [3] there are several identifiers that - need to be understood universally. Some of these identifiers cannot - be understood when an client access the server, but have meaning when - a local process accesses the file. The ability to display and modify - these permissions is permitted over SFTP. - - OWNER The owner of the file. - - - - -Galbraith, et al. Expires June 18, 2003 [Page 13] - -Internet-Draft SSH File Transfer Protocol December 2002 - - - GROUP The group associated with the file. - - EVERYONE The world. - - INTERACTIVE Accessed from an interactive terminal. - - NETWORK Accessed via the network. - - DIALUP Accessed as a dialup user to the server. - - BATCH Accessed from a batch job. - - ANONYMOUS Accessed without any authentication. - - AUTHENTICATED Any authenticated user (opposite of ANONYMOUS). - - SERVICE Access from a system service. - - To avoid conflict, these special identifiers are distinguish by an - appended "@" and should appear in the form "xxxx@" (note: no domain - name after the "@"). For example: ANONYMOUS@. - -5.8 Extended attributes - - The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension - mechanism for vendor-specific extensions. If the flag is specified, - then the `extended_count' field is present. It specifies the number - of extended_type-extended_data pairs that follow. Each of these - pairs specifies an extended attribute. For each of the attributes, - the extended_type field should be a string of the format - "name@domain", where "domain" is a valid, registered domain name and - "name" identifies the method. The IETF may later standardize certain - names that deviate from this format (e.g., that do not contain the - "@" sign). The interpretation of `extended_data' depends on the - type. Implementations SHOULD ignore extended data fields that they - do not understand. - - Additional fields can be added to the attributes by either defining - additional bits to the flags field to indicate their presence, or by - defining extended attributes for them. The extended attributes - mechanism is recommended for most purposes; additional flags bits - should only be defined by an IETF standards action that also - increments the protocol version number. The use of such new fields - MUST be negotiated by the version number in the protocol exchange. - It is a protocol error if a packet with unsupported protocol bits is - received. - - - - - -Galbraith, et al. Expires June 18, 2003 [Page 14] - -Internet-Draft SSH File Transfer Protocol December 2002 - - -6. Requests From the Client to the Server - - Requests from the client to the server represent the various file - system operations. Each request begins with an `id' field, which is - a 32-bit identifier identifying the request (selected by the client). - The same identifier will be returned in the response to the request. - One possible implementation is a monotonically increasing request - sequence number (modulo 2^32). - - Many operations in the protocol operate on open files. The - SSH_FXP_OPEN request can return a file handle (which is an opaque - variable-length string) which may be used to access the file later - (e.g. in a read operation). The client MUST NOT send requests the - server with bogus or closed handles. However, the server MUST - perform adequate checks on the handle in order to avoid security - risks due to fabricated handles. - - This design allows either stateful and stateless server - implementation, as well as an implementation which caches state - between requests but may also flush it. The contents of the file - handle string are entirely up to the server and its design. The - client should not modify or attempt to interpret the file handle - strings. - - The file handle strings MUST NOT be longer than 256 bytes. - -6.1 Request Synchronization and Reordering - - The protocol and implementations MUST process requests relating to - the same file in the order in which they are received. In other - words, if an application submits multiple requests to the server, the - results in the responses will be the same as if it had sent the - requests one at a time and waited for the response in each case. For - example, the server may process non-overlapping read/write requests - to the same file in parallel, but overlapping reads and writes cannot - be reordered or parallelized. However, there are no ordering - restrictions on the server for processing requests from two different - file transfer connections. The server may interleave and parallelize - them at will. - - There are no restrictions on the order in which responses to - outstanding requests are delivered to the client, except that the - server must ensure fairness in the sense that processing of no - request will be indefinitely delayed even if the client is sending - other requests so that there are multiple outstanding requests all - the time. - - - - - -Galbraith, et al. Expires June 18, 2003 [Page 15] - -Internet-Draft SSH File Transfer Protocol December 2002 - - -6.2 File Names - - This protocol represents file names as strings. File names are - assumed to use the slash ('/') character as a directory separator. - - File names starting with a slash are "absolute", and are relative to - the root of the file system. Names starting with any other character - are relative to the user's default directory (home directory). Note - that identifying the user is assumed to take place outside of this - protocol. - - Servers SHOULD interpret a path name component ".." as referring to - the parent directory, and "." as referring to the current directory. - If the server implementation limits access to certain parts of the - file system, it must be extra careful in parsing file names when - enforcing such restrictions. There have been numerous reported - security bugs where a ".." in a path name has allowed access outside - the intended area. - - An empty path name is valid, and it refers to the user's default - directory (usually the user's home directory). - - Otherwise, no syntax is defined for file names by this specification. - Clients should not make any other assumptions; however, they can - splice path name components returned by SSH_FXP_READDIR together - using a slash ('/') as the separator, and that will work as expected. - - In order to comply with IETF Policy on Character Sets and Languages - [2], all filenames are to be encoded in UTF-8. The shortest valid - UTF-8 encoding of the UNICODE data MUST be used. The server is - responsible for converting the UNICODE data to whatever canonical - form it requires. - - For example, if the server requires that precomposed characters - always be used, the server MUST NOT assume the filename as sent by - the client has this attribute, but must do this normalization itself. - - It is understood that the lack of well-defined semantics for file - names may cause interoperability problems between clients and servers - using radically different operating systems. However, this approach - is known to work acceptably with most systems, and alternative - approaches that e.g. treat file names as sequences of structured - components are quite complicated. - -6.3 Opening, Creating, and Closing Files - - Files are opened and created using the SSH_FXP_OPEN message, whose - data part is as follows: - - - -Galbraith, et al. Expires June 18, 2003 [Page 16] - -Internet-Draft SSH File Transfer Protocol December 2002 - - - uint32 id - string filename [UTF-8] - uint32 pflags - ATTRS attrs - - The `id' field is the request identifier as for all requests. - - The `filename' field specifies the file name. See Section ``File - Names'' for more information. - - The `pflags' field is a bitmask. The following bits have been - defined. - - #define SSH_FXF_READ 0x00000001 - #define SSH_FXF_WRITE 0x00000002 - #define SSH_FXF_APPEND 0x00000004 - #define SSH_FXF_CREAT 0x00000008 - #define SSH_FXF_TRUNC 0x00000010 - #define SSH_FXF_EXCL 0x00000020 - #define SSH_FXF_TEXT 0x00000040 - - These have the following meanings: - - SSH_FXF_READ - Open the file for reading. - - SSH_FXF_WRITE - Open the file for writing. If both this and SSH_FXF_READ are - specified, the file is opened for both reading and writing. - - SSH_FXF_APPEND - Force all writes to append data at the end of the file. The - offset parameter to write will be ignored. - - SSH_FXF_CREAT - If this flag is specified, then a new file will be created if one - does not already exist (if O_TRUNC is specified, the new file will - be truncated to zero length if it previously exists). - - SSH_FXF_TRUNC - Forces an existing file with the same name to be truncated to zero - length when creating a file by specifying SSH_FXF_CREAT. - SSH_FXF_CREAT MUST also be specified if this flag is used. - - SSH_FXF_EXCL - Causes the request to fail if the named file already exists. - SSH_FXF_CREAT MUST also be specified if this flag is used. - - - - -Galbraith, et al. Expires June 18, 2003 [Page 17] - -Internet-Draft SSH File Transfer Protocol December 2002 - - - SSH_FXF_TEXT - Indicates that the server should treat the file as text and - convert it to the canonical newline convention in use. (See - Determining Server Newline Convention. (Section 4.3) - - When a file is opened with the FXF_TEXT flag, the offset field in - both the read and write function are ignored. - - Servers MUST correctly process multiple parallel reads and writes - correctly in this mode. Naturally, it is permissible for them to - do this by serializing the requests. It would not be possible for - a client to reliably detect a server that does not implement - parallel writes in time to prevent damage. - - Clients SHOULD use the SSH_FXF_APPEND flag to append data to a - text file rather then using write with a calculated offset. - - To support seeks on text file the following SSH_FXP_EXTENDED - packet is defined. - - - - string "text-seek" - string file-handle - uint64 line-number - - line-number is the index of the line number to seek to, where byte - 0 in the file is line number 0, and the byte directly following - the first newline sequence in the file is line number 1 and so on. - - The response to a "text-seek" request is an SSH_FXP_STATUS - message. - - An attempt to seek past the end-of-file should result in a - SSH_FX_EOF status. - - Servers SHOULD support at least one "text-seek" in order to - support resume. However, a client MUST be prepared to receive - SSH_FX_OP_UNSUPPORTED when attempting a "text-seek" operation. - The client can then try a fall-back strategy, if it has one. - - Clients MUST be prepared to handle SSH_FX_OP_UNSUPPORTED returned - for read or write operations that are not sequential. - - The `attrs' field specifies the initial attributes for the file. - Default values will be used for those attributes that are not - specified. See Section ``File Attributes'' for more information. - - - - -Galbraith, et al. Expires June 18, 2003 [Page 18] - -Internet-Draft SSH File Transfer Protocol December 2002 - - - The response to this message will be either SSH_FXP_HANDLE (if the - operation is successful) or SSH_FXP_STATUS (if the operation fails). - - A file is closed by using the SSH_FXP_CLOSE request. Its data field - has the following format: - - uint32 id - string handle - - where `id' is the request identifier, and `handle' is a handle - previously returned in the response to SSH_FXP_OPEN or - SSH_FXP_OPENDIR. The handle becomes invalid immediately after this - request has been sent. - - The response to this request will be a SSH_FXP_STATUS message. One - should note that on some server platforms even a close can fail. - This can happen e.g. if the server operating system caches writes, - and an error occurs while flushing cached writes during the close. - -6.4 Reading and Writing - - Once a file has been opened, it can be read using the following - message: - - byte SSH_FXP_READ - uint32 id - string handle - uint64 offset - uint32 len - - where `id' is the request identifier, `handle' is an open file handle - returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) relative - to the beginning of the file from where to start reading, and `len' - is the maximum number of bytes to read. - - In response to this request, the server will read as many bytes as it - can from the file (up to `len'), and return them in a SSH_FXP_DATA - message. If an error occurs or EOF is encountered before reading any - data, the server will respond with SSH_FXP_STATUS. - - For normal disk files, it is normally guaranteed that this will read - the specified number of bytes, or up to end of file. However, if the - read length is very long, the server may truncate it if it doesn't - support packets of that length. See General Packet Format (Section - 3). - - For e.g. device files this may return fewer bytes than requested. - - - - -Galbraith, et al. Expires June 18, 2003 [Page 19] - -Internet-Draft SSH File Transfer Protocol December 2002 - - - Writing to a file is achieved using the following message: - - byte SSH_FXP_WRITE - uint32 id - string handle - uint64 offset - string data - - where `id' is a request identifier, `handle' is a file handle - returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) from the - beginning of the file where to start writing, and `data' is the data - to be written. - - The write will extend the file if writing beyond the end of the file. - It is legal to write way beyond the end of the file; the semantics - are to write zeroes from the end of the file to the specified offset - and then the data. On most operating systems, such writes do not - allocate disk space but instead leave "holes" in the file. - - The server responds to a write request with a SSH_FXP_STATUS message. - -6.5 Removing and Renaming Files - - Files can be removed using the SSH_FXP_REMOVE message. It has the - following format: - - uint32 id - string filename [UTF-8] - - where `id' is the request identifier and `filename' is the name of - the file to be removed. See Section ``File Names'' for more - information. This request cannot be used to remove directories. - - The server will respond to this request with a SSH_FXP_STATUS - message. - - Files (and directories) can be renamed using the SSH_FXP_RENAME - message. Its data is as follows: - - uint32 id - string oldpath [UTF-8] - string newpath [UTF-8] - - where `id' is the request identifier, `oldpath' is the name of an - existing file or directory, and `newpath' is the new name for the - file or directory. It is an error if there already exists a file - with the name specified by newpath. The server may also fail rename - requests in other situations, for example if `oldpath' and `newpath' - - - -Galbraith, et al. Expires June 18, 2003 [Page 20] - -Internet-Draft SSH File Transfer Protocol December 2002 - - - point to different file systems on the server. - - The server will respond to this request with a SSH_FXP_STATUS - message. - -6.6 Creating and Deleting Directories - - New directories can be created using the SSH_FXP_MKDIR request. It - has the following format: - - uint32 id - string path [UTF-8] - ATTRS attrs - - where `id' is the request identifier. - - `path' specifies the directory to be created. See Section ``File - Names'' for more information on file names. - - `attrs' specifies the attributes that should be applied to it upon - creation. Attributes are discussed in more detail in Section ``File - Attributes''. - - The server will respond to this request with a SSH_FXP_STATUS - message. If a file or directory with the specified path already - exists, an error will be returned. - - Directories can be removed using the SSH_FXP_RMDIR request, which has - the following format: - - uint32 id - string path [UTF-8] - - where `id' is the request identifier, and `path' specifies the - directory to be removed. See Section ``File Names'' for more - information on file names. - - The server responds to this request with a SSH_FXP_STATUS message. - Errors may be returned from this operation for various reasons, - including, but not limited to, the path does not exist, the path does - not refer to a directory object, the directory is not empty, or the - user has insufficient access or permission to perform the requested - operation. - -6.7 Scanning Directories - - The files in a directory can be listed using the SSH_FXP_OPENDIR and - SSH_FXP_READDIR requests. Each SSH_FXP_READDIR request returns one - - - -Galbraith, et al. Expires June 18, 2003 [Page 21] - -Internet-Draft SSH File Transfer Protocol December 2002 - - - or more file names with full file attributes for each file. The - client should call SSH_FXP_READDIR repeatedly until it has found the - file it is looking for or until the server responds with a - SSH_FXP_STATUS message indicating an error (normally SSH_FX_EOF if - there are no more files in the directory). The client should then - close the handle using the SSH_FXP_CLOSE request. - - The SSH_FXP_OPENDIR opens a directory for reading. It has the - following format: - - uint32 id - string path [UTF-8] - - where `id' is the request identifier and `path' is the path name of - the directory to be listed (without any trailing slash). See Section - ``File Names'' for more information on file names. This will return - an error if the path does not specify a directory or if the directory - is not readable. The server will respond to this request with either - a SSH_FXP_HANDLE or a SSH_FXP_STATUS message. - - Once the directory has been successfully opened, files (and - directories) contained in it can be listed using SSH_FXP_READDIR - requests. These are of the format - - uint32 id - string handle - - where `id' is the request identifier, and `handle' is a handle - returned by SSH_FXP_OPENDIR. (It is a protocol error to attempt to - use an ordinary file handle returned by SSH_FXP_OPEN.) - - The server responds to this request with either a SSH_FXP_NAME or a - SSH_FXP_STATUS message. One or more names may be returned at a time. - Full status information is returned for each name in order to speed - up typical directory listings. - - If there are no more names available to be read, the server MUST - respond with a SSH_FXP_STATUS message with error code of SSH_FX_EOF. - - When the client no longer wishes to read more names from the - directory, it SHOULD call SSH_FXP_CLOSE for the handle. The handle - should be closed regardless of whether an error has occurred or not. - -6.8 Retrieving File Attributes - - Very often, file attributes are automatically returned by - SSH_FXP_READDIR. However, sometimes there is need to specifically - retrieve the attributes for a named file. This can be done using the - - - -Galbraith, et al. Expires June 18, 2003 [Page 22] - -Internet-Draft SSH File Transfer Protocol December 2002 - - - SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests. - - SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT - follows symbolic links on the server, whereas SSH_FXP_LSTAT does not - follow symbolic links. Both have the same format: - - uint32 id - string path [UTF-8] - uint32 flags - - where `id' is the request identifier, and `path' specifies the file - system object for which status is to be returned. The server - responds to this request with either SSH_FXP_ATTRS or SSH_FXP_STATUS. - - The flags field specify the attribute flags in which the client has - particular interest. This is a hint to the server. For example, - because retrieving owner / group and acl information can be an - expensive operation under some operating systems, the server may - choose not to retrieve this information unless the client expresses a - specific interest in it. - - The client has no guarantee the server will provide all the fields - that it has expressed an interest in. - - SSH_FXP_FSTAT differs from the others in that it returns status - information for an open file (identified by the file handle). Its - format is as follows: - - uint32 id - string handle - uint32 flags - - where `id' is the request identifier and `handle' is a file handle - returned by SSH_FXP_OPEN. The server responds to this request with - SSH_FXP_ATTRS or SSH_FXP_STATUS. - -6.9 Setting File Attributes - - File attributes may be modified using the SSH_FXP_SETSTAT and - SSH_FXP_FSETSTAT requests. These requests are used for operations - such as changing the ownership, permissions or access times, as well - as for truncating a file. - - The SSH_FXP_SETSTAT request is of the following format: - - - - - - - -Galbraith, et al. Expires June 18, 2003 [Page 23] - -Internet-Draft SSH File Transfer Protocol December 2002 - - - uint32 id - string path [UTF-8] - ATTRS attrs - - where `id' is the request identifier, `path' specifies the file - system object (e.g. file or directory) whose attributes are to be - modified, and `attrs' specifies the modifications to be made to its - attributes. Attributes are discussed in more detail in Section - ``File Attributes''. - - An error will be returned if the specified file system object does - not exist or the user does not have sufficient rights to modify the - specified attributes. The server responds to this request with a - SSH_FXP_STATUS message. - - The SSH_FXP_FSETSTAT request modifies the attributes of a file which - is already open. It has the following format: - - uint32 id - string handle - ATTRS attrs - - where `id' is the request identifier, `handle' (MUST be returned by - SSH_FXP_OPEN) identifies the file whose attributes are to be - modified, and `attrs' specifies the modifications to be made to its - attributes. Attributes are discussed in more detail in Section - ``File Attributes''. The server will respond to this request with - SSH_FXP_STATUS. - -6.10 Dealing with Symbolic links - - The SSH_FXP_READLINK request may be used to read the target of a - symbolic link. It would have a data part as follows: - - uint32 id - string path [UTF-8] - - where `id' is the request identifier and `path' specifies the path - name of the symlink to be read. - - The server will respond with a SSH_FXP_NAME packet containing only - one name and a dummy attributes value. The name in the returned - packet contains the target of the link. If an error occurs, the - server may respond with SSH_FXP_STATUS. - - The SSH_FXP_SYMLINK request will create a symbolic link on the - server. It is of the following format - - - - -Galbraith, et al. Expires June 18, 2003 [Page 24] - -Internet-Draft SSH File Transfer Protocol December 2002 - - - uint32 id - string linkpath [UTF-8] - string targetpath [UTF-8] - - where `id' is the request identifier, `linkpath' specifies the path - name of the symlink to be created and `targetpath' specifies the - target of the symlink. The server shall respond with a - SSH_FXP_STATUS indicating either success (SSH_FX_OK) or an error - condition. - -6.11 Canonicalizing the Server-Side Path Name - - The SSH_FXP_REALPATH request can be used to have the server - canonicalize any given path name to an absolute path. This is useful - for converting path names containing ".." components or relative - pathnames without a leading slash into absolute paths. The format of - the request is as follows: - - uint32 id - string path [UTF-8] - - where `id' is the request identifier and `path' specifies the path - name to be canonicalized. The server will respond with a - SSH_FXP_NAME packet containing the name in canonical form and a dummy - attributes value. If an error occurs, the server may also respond - with SSH_FXP_STATUS. - -6.11.1 Best practice for dealing with paths - - The client SHOULD treat the results of SSH_FXP_REALPATH as a - canonical absolute path, even if the path does not appear to be - absolute. A client that use REALPATH(".") and treats the result as - absolute, even if there is no leading slash, will continue to - function correctly, even when talking to a Windows NT or VMS style - system, where absolute paths may not begin with a slash. - - For example, if the client wishes to change directory up, and the - server has returned "c:/x/y/z" from REALPATH, the client SHOULD use - "c:/x/y/z/..". - - As a second example, if the client wishes to open the file "x.txt" in - the current directory, and server has returned "dka100:/x/y/z" as the - canonical path of the directory, the client SHOULD open "dka100:/x/y/ - z/x.txt" - - - - - - - -Galbraith, et al. Expires June 18, 2003 [Page 25] - -Internet-Draft SSH File Transfer Protocol December 2002 - - -7. Responses from the Server to the Client - - The server responds to the client using one of a few response - packets. All requests can return a SSH_FXP_STATUS response upon - failure. When the operation is successful, any of the responses may - be returned (depending on the operation). If no data needs to be - returned to the client, the SSH_FXP_STATUS response with SSH_FX_OK - status is appropriate. Otherwise, the SSH_FXP_HANDLE message is used - to return a file handle (for SSH_FXP_OPEN and SSH_FXP_OPENDIR - requests), SSH_FXP_DATA is used to return data from SSH_FXP_READ, - SSH_FXP_NAME is used to return one or more file names from a - SSH_FXP_READDIR or SSH_FXP_REALPATH request, and SSH_FXP_ATTRS is - used to return file attributes from SSH_FXP_STAT, SSH_FXP_LSTAT, and - SSH_FXP_FSTAT requests. - - Exactly one response will be returned for each request. Each - response packet contains a request identifier which can be used to - match each response with the corresponding request. Note that it is - legal to have several requests outstanding simultaneously, and the - server is allowed to send responses to them in a different order from - the order in which the requests were sent (the result of their - execution, however, is guaranteed to be as if they had been processed - one at a time in the order in which the requests were sent). - - Response packets are of the same general format as request packets. - Each response packet begins with the request identifier. - - The format of the data portion of the SSH_FXP_STATUS response is as - follows: - - uint32 id - uint32 error/status code - string error message (ISO-10646 UTF-8 [RFC-2279]) - string language tag (as defined in [RFC-1766]) - - where `id' is the request identifier, and `error/status code' - indicates the result of the requested operation. The value SSH_FX_OK - indicates success, and all other values indicate failure. - - Currently, the following values are defined (other values may be - defined by future versions of this protocol): - - - - - - - - - - -Galbraith, et al. Expires June 18, 2003 [Page 26] - -Internet-Draft SSH File Transfer Protocol December 2002 - - - #define SSH_FX_OK 0 - #define SSH_FX_EOF 1 - #define SSH_FX_NO_SUCH_FILE 2 - #define SSH_FX_PERMISSION_DENIED 3 - #define SSH_FX_FAILURE 4 - #define SSH_FX_BAD_MESSAGE 5 - #define SSH_FX_NO_CONNECTION 6 - #define SSH_FX_CONNECTION_LOST 7 - #define SSH_FX_OP_UNSUPPORTED 8 - #define SSH_FX_INVALID_HANDLE 9 - #define SSH_FX_NO_SUCH_PATH 10 - #define SSH_FX_FILE_ALREADY_EXISTS 11 - #define SSH_FX_WRITE_PROTECT 12 - #define SSH_FX_NO_MEDIA 13 - - SSH_FX_OK - Indicates successful completion of the operation. - - SSH_FX_EOF - indicates end-of-file condition; for SSH_FX_READ it means that no - more data is available in the file, and for SSH_FX_READDIR it - indicates that no more files are contained in the directory. - - SSH_FX_NO_SUCH_FILE - is returned when a reference is made to a file which does not - exist. - - SSH_FX_PERMISSION_DENIED - is returned when the authenticated user does not have sufficient - permissions to perform the operation. - - SSH_FX_FAILURE - is a generic catch-all error message; it should be returned if an - error occurs for which there is no more specific error code - defined. - - SSH_FX_BAD_MESSAGE - may be returned if a badly formatted packet or protocol - incompatibility is detected. - - SSH_FX_NO_CONNECTION - is a pseudo-error which indicates that the client has no - connection to the server (it can only be generated locally by the - client, and MUST NOT be returned by servers). - - SSH_FX_CONNECTION_LOST - is a pseudo-error which indicates that the connection to the - server has been lost (it can only be generated locally by the - - - -Galbraith, et al. Expires June 18, 2003 [Page 27] - -Internet-Draft SSH File Transfer Protocol December 2002 - - - client, and MUST NOT be returned by servers). - - SSH_FX_OP_UNSUPPORTED - indicates that an attempt was made to perform an operation which - is not supported for the server (it may be generated locally by - the client if e.g. the version number exchange indicates that a - required feature is not supported by the server, or it may be - returned by the server if the server does not implement an - operation). - - SSH_FX_INVALID_HANDLE - The handle value was invalid. - - SSH_FX_NO_SUCH_PATH - The file path does not exist or is invalid. - - SSH_FX_FILE_ALREADY_EXISTS - The file already exists. - - SSH_FX_WRITE_PROTECT - The file is on read only media, or the media is write protected. - - SSH_FX_NO_MEDIA - The requested operation can not be completed because there is no - media available in the drive. - - The SSH_FXP_HANDLE response has the following format: - - uint32 id - string handle - - where `id' is the request identifier, and `handle' is an arbitrary - string that identifies an open file or directory on the server. The - handle is opaque to the client; the client MUST NOT attempt to - interpret or modify it in any way. The length of the handle string - MUST NOT exceed 256 data bytes. - - The SSH_FXP_DATA response has the following format: - - uint32 id - string data - - where `id' is the request identifier, and `data' is an arbitrary byte - string containing the requested data. The data string may be at most - the number of bytes requested in a SSH_FXP_READ request, but may also - be shorter if end of file is reached or if the read is from something - other than a regular file. - - - - -Galbraith, et al. Expires June 18, 2003 [Page 28] - -Internet-Draft SSH File Transfer Protocol December 2002 - - - The SSH_FXP_NAME response has the following format: - - uint32 id - uint32 count - repeats count times: - string filename [UTF-8] - ATTRS attrs - - where `id' is the request identifier, `count' is the number of names - returned in this response, and the remaining fields repeat `count' - times (so that all three fields are first included for the first - file, then for the second file, etc). In the repeated part, - `filename' is a file name being returned (for SSH_FXP_READDIR, it - will be a relative name within the directory, without any path - components; for SSH_FXP_REALPATH it will be an absolute path name), - and `attrs' is the attributes of the file as described in Section - ``File Attributes''. - - The SSH_FXP_ATTRS response has the following format: - - uint32 id - ATTRS attrs - - where `id' is the request identifier, and `attrs' is the returned - file attributes as described in Section ``File Attributes''. - - - - - - - - - - - - - - - - - - - - - - - - - - -Galbraith, et al. Expires June 18, 2003 [Page 29] - -Internet-Draft SSH File Transfer Protocol December 2002 - - -8. Vendor-Specific Extensions - - The SSH_FXP_EXTENDED request provides a generic extension mechanism - for adding vendor-specific commands. The request has the following - format: - - uint32 id - string extended-request - ... any request-specific data ... - - where `id' is the request identifier, and `extended-request' is a - string of the format "name@domain", where domain is an internet - domain name of the vendor defining the request. The rest of the - request is completely vendor-specific, and servers should only - attempt to interpret it if they recognize the `extended-request' - name. - - The server may respond to such requests using any of the response - packets defined in Section ``Responses from the Server to the - Client''. Additionally, the server may also respond with a - SSH_FXP_EXTENDED_REPLY packet, as defined below. If the server does - not recognize the `extended-request' name, then the server MUST - respond with SSH_FXP_STATUS with error/status set to - SSH_FX_OP_UNSUPPORTED. - - The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary - extension-specific data from the server to the client. It is of the - following format: - - uint32 id - ... any request-specific data ... - - There is a range of packet types reserved for use by extensions. In - order to avoid collision, extensions that turn on the use of - additional packet types should determine those numbers dynamically. - - The suggested way of doing this is have an extension request from the - client to the server that enables the extension; the extension - response from the server to the client would specify the actual type - values to use, in additional to any other data. - - Extension authors should be mindful of the limited range of packet - types available (there are only 45 values available) and avoid - requiring a new packet type where possible. - - - - - - - -Galbraith, et al. Expires June 18, 2003 [Page 30] - -Internet-Draft SSH File Transfer Protocol December 2002 - - -9. Security Considerations - - This protocol assumes that it is run over a secure channel and that - the endpoints of the channel have been authenticated. Thus, this - protocol assumes that it is externally protected from network-level - attacks. - - This protocol provides file system access to arbitrary files on the - server (only constrained by the server implementation). It is the - responsibility of the server implementation to enforce any access - controls that may be required to limit the access allowed for any - particular user (the user being authenticated externally to this - protocol, typically using the SSH User Authentication Protocol [8]. - - Care must be taken in the server implementation to check the validity - of received file handle strings. The server should not rely on them - directly; it MUST check the validity of each handle before relying on - it. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Galbraith, et al. Expires June 18, 2003 [Page 31] - -Internet-Draft SSH File Transfer Protocol December 2002 - - -10. Changes from previous protocol versions - - The SSH File Transfer Protocol has changed over time, before it's - standardization. The following is a description of the incompatible - changes between different versions. - -10.1 Changes between versions 4 and 3 - - Many of the changes between version 4 and version 3 are to the - attribute structure to make it more flexible for non-unix platforms. - - o Clarify the use of stderr by the server. - - o Clarify handling of very large read requests by the server. - - o Make all filenames UTF-8. - - o Added 'newline' extension. - - o Made time fields 64 bit, and optionally have nanosecond resultion. - - o Made file attribute owner and group strings so they can actually - be used on disparate systems. - - o Added createtime field, and added separate flags for atime, - createtime, and mtime so they can be set separately. - - o Split the file type out of the permissions field and into it's own - field (which is always present.) - - o Added acl attribute. - - o Added SSH_FXF_TEXT file open flag. - - o Added flags field to the get stat commands so that the client can - specifically request information the server might not normally - included for performance reasons. - - o Removed the long filename from the names structure-- it can now be - built from information available in the attrs structure. - - o Added reserved range of packet numbers for extensions. - - o Added several additional error codes. - - - - - - - -Galbraith, et al. Expires June 18, 2003 [Page 32] - -Internet-Draft SSH File Transfer Protocol December 2002 - - -10.2 Changes between versions 3 and 2 - - o The SSH_FXP_READLINK and SSH_FXP_SYMLINK messages were added. - - o The SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY messages were - added. - - o The SSH_FXP_STATUS message was changed to include fields `error - message' and `language tag'. - - -10.3 Changes between versions 2 and 1 - - o The SSH_FXP_RENAME message was added. - - -10.4 Changes between versions 1 and 0 - - o Implementation changes, no actual protocol changes. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Galbraith, et al. Expires June 18, 2003 [Page 33] - -Internet-Draft SSH File Transfer Protocol December 2002 - - -11. Trademark Issues - - "ssh" is a registered trademark of SSH Communications Security Corp - in the United States and/or other countries. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Galbraith, et al. Expires June 18, 2003 [Page 34] - -Internet-Draft SSH File Transfer Protocol December 2002 - - -References - - [1] Dierks, T., Allen, C., Treese, W., Karlton, P., Freier, A. and - P. Kocher, "The TLS Protocol Version 1.0", RFC 2246, January - 1999. - - [2] Alvestrand, H., "IETF Policy on Character Sets and Languages", - BCP 18, RFC 2277, January 1998. - - [3] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., Beame, - C., Eisler, M. and D. Noveck, "NFS version 4 Protocol", RFC - 3010, December 2000. - - [4] Institute of Electrical and Electronics Engineers, "Information - Technology - Portable Operating System Interface (POSIX) - Part - 1: System Application Program Interface (API) [C Language]", - IEEE Standard 1003.2, 1996. - - [5] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S. - Lehtinen, "SSH Protocol Architecture", - draft-ietf-secsh-architecture-13 (work in progress), September - 2002. - - [6] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S. - Lehtinen, "SSH Protocol Transport Protocol", - draft-ietf-secsh-transport-15 (work in progress), September - 2002. - - [7] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S. - Lehtinen, "SSH Connection Protocol", draft-ietf-secsh-connect-16 - (work in progress), September 2002. - - [8] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S. - Lehtinen, "SSH Authentication Protocol", - draft-ietf-secsh-userauth-16 (work in progress), September 2002. - - -Authors' Addresses - - Joseph Galbraith - VanDyke Software - 4848 Tramway Ridge Blvd - Suite 101 - Albuquerque, NM 87111 - US - - Phone: +1 505 332 5700 - EMail: [email protected] - - - -Galbraith, et al. Expires June 18, 2003 [Page 35] - -Internet-Draft SSH File Transfer Protocol December 2002 - - - Tatu Ylonen - SSH Communications Security Corp - Fredrikinkatu 42 - HELSINKI FIN-00100 - Finland - - EMail: [email protected] - - - Sami Lehtinen - SSH Communications Security Corp - Fredrikinkatu 42 - HELSINKI FIN-00100 - Finland - - EMail: [email protected] - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Galbraith, et al. Expires June 18, 2003 [Page 36] - -Internet-Draft SSH File Transfer Protocol December 2002 - - -Intellectual Property Statement - - The IETF takes no position regarding the validity or scope of any - intellectual property 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; neither does it represent that it - has made any effort to identify any such rights. Information on the - IETF's procedures with respect to rights in standards-track and - standards-related documentation can be found in BCP-11. Copies of - claims of rights made available for publication 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 implementors or users of this specification can - be obtained from the IETF Secretariat. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights which may cover technology that may be required to practice - this standard. Please address the information to the IETF Executive - Director. - - -Full Copyright Statement - - Copyright (C) The Internet Society (2002). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assignees. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION - - - -Galbraith, et al. Expires June 18, 2003 [Page 37] - -Internet-Draft SSH File Transfer Protocol December 2002 - - - HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF - MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Galbraith, et al. Expires June 18, 2003 [Page 38] - - diff --git a/lib/ssh/doc/standard/draft-ietf-secsh-transport-17.2.ps b/lib/ssh/doc/standard/draft-ietf-secsh-transport-17.2.ps deleted file mode 100644 index d692285b4e..0000000000 --- a/lib/ssh/doc/standard/draft-ietf-secsh-transport-17.2.ps +++ /dev/null @@ -1,3205 +0,0 @@ -%!PS-Adobe-3.0 -%%BoundingBox: 75 0 595 747 -%%Title: Enscript Output -%%For: Magnus Thoang -%%Creator: GNU enscript 1.6.1 -%%CreationDate: Fri Oct 31 13:35:14 2003 -%%Orientation: Portrait -%%Pages: 15 0 -%%DocumentMedia: A4 595 842 0 () () -%%DocumentNeededResources: (atend) -%%EndComments -%%BeginProlog -%%BeginProcSet: PStoPS 1 15 -userdict begin -[/showpage/erasepage/copypage]{dup where{pop dup load - type/operatortype eq{1 array cvx dup 0 3 index cvx put - bind def}{pop}ifelse}{pop}ifelse}forall -[/letter/legal/executivepage/a4/a4small/b5/com10envelope - /monarchenvelope/c5envelope/dlenvelope/lettersmall/note - /folio/quarto/a5]{dup where{dup wcheck{exch{}put} - {pop{}def}ifelse}{pop}ifelse}forall -/setpagedevice {pop}bind 1 index where{dup wcheck{3 1 roll put} - {pop def}ifelse}{def}ifelse -/PStoPSmatrix matrix currentmatrix def -/PStoPSxform matrix def/PStoPSclip{clippath}def -/defaultmatrix{PStoPSmatrix exch PStoPSxform exch concatmatrix}bind def -/initmatrix{matrix defaultmatrix setmatrix}bind def -/initclip[{matrix currentmatrix PStoPSmatrix setmatrix - [{currentpoint}stopped{$error/newerror false put{newpath}} - {/newpath cvx 3 1 roll/moveto cvx 4 array astore cvx}ifelse] - {[/newpath cvx{/moveto cvx}{/lineto cvx} - {/curveto cvx}{/closepath cvx}pathforall]cvx exch pop} - stopped{$error/errorname get/invalidaccess eq{cleartomark - $error/newerror false put cvx exec}{stop}ifelse}if}bind aload pop - /initclip dup load dup type dup/operatortype eq{pop exch pop} - {dup/arraytype eq exch/packedarraytype eq or - {dup xcheck{exch pop aload pop}{pop cvx}ifelse} - {pop cvx}ifelse}ifelse - {newpath PStoPSclip clip newpath exec setmatrix} bind aload pop]cvx def -/initgraphics{initmatrix newpath initclip 1 setlinewidth - 0 setlinecap 0 setlinejoin []0 setdash 0 setgray - 10 setmiterlimit}bind def -end -%%EndProcSet -%%BeginResource: procset Enscript-Prolog 1.6 1 -% -% Procedures. -% - -/_S { % save current state - /_s save def -} def -/_R { % restore from saved state - _s restore -} def - -/S { % showpage protecting gstate - gsave - showpage - grestore -} bind def - -/MF { % fontname newfontname -> - make a new encoded font - /newfontname exch def - /fontname exch def - - /fontdict fontname findfont def - /newfont fontdict maxlength dict def - - fontdict { - exch - dup /FID eq { - % skip FID pair - pop pop - } { - % copy to the new font dictionary - exch newfont 3 1 roll put - } ifelse - } forall - - newfont /FontName newfontname put - - % insert only valid encoding vectors - encoding_vector length 256 eq { - newfont /Encoding encoding_vector put - } if - - newfontname newfont definefont pop -} def - -/SF { % fontname width height -> - set a new font - /height exch def - /width exch def - - findfont - [width 0 0 height 0 0] makefont setfont -} def - -/SUF { % fontname width height -> - set a new user font - /height exch def - /width exch def - - /F-gs-user-font MF - /F-gs-user-font width height SF -} def - -/M {moveto} bind def -/s {show} bind def - -/Box { % x y w h -> - define box path - /d_h exch def /d_w exch def /d_y exch def /d_x exch def - d_x d_y moveto - d_w 0 rlineto - 0 d_h rlineto - d_w neg 0 rlineto - closepath -} def - -/bgs { % x y height blskip gray str -> - show string with bg color - /str exch def - /gray exch def - /blskip exch def - /height exch def - /y exch def - /x exch def - - gsave - x y blskip sub str stringwidth pop height Box - gray setgray - fill - grestore - x y M str s -} def - -% Highlight bars. -/highlight_bars { % nlines lineheight output_y_margin gray -> - - gsave - setgray - /ymarg exch def - /lineheight exch def - /nlines exch def - - % This 2 is just a magic number to sync highlight lines to text. - 0 d_header_y ymarg sub 2 sub translate - - /cw d_output_w cols div def - /nrows d_output_h ymarg 2 mul sub lineheight div cvi def - - % for each column - 0 1 cols 1 sub { - cw mul /xp exch def - - % for each rows - 0 1 nrows 1 sub { - /rn exch def - rn lineheight mul neg /yp exch def - rn nlines idiv 2 mod 0 eq { - % Draw highlight bar. 4 is just a magic indentation. - xp 4 add yp cw 8 sub lineheight neg Box fill - } if - } for - } for - - grestore -} def - -% Line highlight bar. -/line_highlight { % x y width height gray -> - - gsave - /gray exch def - Box gray setgray fill - grestore -} def - -% Column separator lines. -/column_lines { - gsave - .1 setlinewidth - 0 d_footer_h translate - /cw d_output_w cols div def - 1 1 cols 1 sub { - cw mul 0 moveto - 0 d_output_h rlineto stroke - } for - grestore -} def - -% Column borders. -/column_borders { - gsave - .1 setlinewidth - 0 d_footer_h moveto - 0 d_output_h rlineto - d_output_w 0 rlineto - 0 d_output_h neg rlineto - closepath stroke - grestore -} def - -% Do the actual underlay drawing -/draw_underlay { - ul_style 0 eq { - ul_str true charpath stroke - } { - ul_str show - } ifelse -} def - -% Underlay -/underlay { % - -> - - gsave - 0 d_page_h translate - d_page_h neg d_page_w atan rotate - - ul_gray setgray - ul_font setfont - /dw d_page_h dup mul d_page_w dup mul add sqrt def - ul_str stringwidth pop dw exch sub 2 div ul_h_ptsize -2 div moveto - draw_underlay - grestore -} def - -/user_underlay { % - -> - - gsave - ul_x ul_y translate - ul_angle rotate - ul_gray setgray - ul_font setfont - 0 0 ul_h_ptsize 2 div sub moveto - draw_underlay - grestore -} def - -% Page prefeed -/page_prefeed { % bool -> - - statusdict /prefeed known { - statusdict exch /prefeed exch put - } { - pop - } ifelse -} def - -% Wrapped line markers -/wrapped_line_mark { % x y charwith charheight type -> - - /type exch def - /h exch def - /w exch def - /y exch def - /x exch def - - type 2 eq { - % Black boxes (like TeX does) - gsave - 0 setlinewidth - x w 4 div add y M - 0 h rlineto w 2 div 0 rlineto 0 h neg rlineto - closepath fill - grestore - } { - type 3 eq { - % Small arrows - gsave - .2 setlinewidth - x w 2 div add y h 2 div add M - w 4 div 0 rlineto - x w 4 div add y lineto stroke - - x w 4 div add w 8 div add y h 4 div add M - x w 4 div add y lineto - w 4 div h 8 div rlineto stroke - grestore - } { - % do nothing - } ifelse - } ifelse -} def - -% EPSF import. - -/BeginEPSF { - /b4_Inc_state save def % Save state for cleanup - /dict_count countdictstack def % Count objects on dict stack - /op_count count 1 sub def % Count objects on operand stack - userdict begin - /showpage { } def - 0 setgray 0 setlinecap - 1 setlinewidth 0 setlinejoin - 10 setmiterlimit [ ] 0 setdash newpath - /languagelevel where { - pop languagelevel - 1 ne { - false setstrokeadjust false setoverprint - } if - } if -} bind def - -/EndEPSF { - count op_count sub { pos } repeat % Clean up stacks - countdictstack dict_count sub { end } repeat - b4_Inc_state restore -} bind def - -% Check PostScript language level. -/languagelevel where { - pop /gs_languagelevel languagelevel def -} { - /gs_languagelevel 1 def -} ifelse -%%EndResource -%%BeginResource: procset Enscript-Encoding-88591 1.6 1 -/encoding_vector [ -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/space /exclam /quotedbl /numbersign -/dollar /percent /ampersand /quoteright -/parenleft /parenright /asterisk /plus -/comma /hyphen /period /slash -/zero /one /two /three -/four /five /six /seven -/eight /nine /colon /semicolon -/less /equal /greater /question -/at /A /B /C -/D /E /F /G -/H /I /J /K -/L /M /N /O -/P /Q /R /S -/T /U /V /W -/X /Y /Z /bracketleft -/backslash /bracketright /asciicircum /underscore -/quoteleft /a /b /c -/d /e /f /g -/h /i /j /k -/l /m /n /o -/p /q /r /s -/t /u /v /w -/x /y /z /braceleft -/bar /braceright /tilde /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/space /exclamdown /cent /sterling -/currency /yen /brokenbar /section -/dieresis /copyright /ordfeminine /guillemotleft -/logicalnot /hyphen /registered /macron -/degree /plusminus /twosuperior /threesuperior -/acute /mu /paragraph /bullet -/cedilla /onesuperior /ordmasculine /guillemotright -/onequarter /onehalf /threequarters /questiondown -/Agrave /Aacute /Acircumflex /Atilde -/Adieresis /Aring /AE /Ccedilla -/Egrave /Eacute /Ecircumflex /Edieresis -/Igrave /Iacute /Icircumflex /Idieresis -/Eth /Ntilde /Ograve /Oacute -/Ocircumflex /Otilde /Odieresis /multiply -/Oslash /Ugrave /Uacute /Ucircumflex -/Udieresis /Yacute /Thorn /germandbls -/agrave /aacute /acircumflex /atilde -/adieresis /aring /ae /ccedilla -/egrave /eacute /ecircumflex /edieresis -/igrave /iacute /icircumflex /idieresis -/eth /ntilde /ograve /oacute -/ocircumflex /otilde /odieresis /divide -/oslash /ugrave /uacute /ucircumflex -/udieresis /yacute /thorn /ydieresis -] def -%%EndResource -%%EndProlog -%%BeginSetup -%%IncludeResource: font Courier-Bold -%%IncludeResource: font Courier -/HFpt_w 10 def -/HFpt_h 10 def -/Courier-Bold /HF-gs-font MF -/HF /HF-gs-font findfont [HFpt_w 0 0 HFpt_h 0 0] makefont def -/Courier /F-gs-font MF -/F-gs-font 10 10 SF -/#copies 1 def -/d_page_w 520 def -/d_page_h 747 def -/d_header_x 0 def -/d_header_y 747 def -/d_header_w 520 def -/d_header_h 0 def -/d_footer_x 0 def -/d_footer_y 0 def -/d_footer_w 520 def -/d_footer_h 0 def -/d_output_w 520 def -/d_output_h 747 def -/cols 1 def -userdict/PStoPSxform PStoPSmatrix matrix currentmatrix - matrix invertmatrix matrix concatmatrix - matrix invertmatrix put -%%EndSetup -%%Page: (0,1) 1 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 1 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 701 M -(Network Working Group T. Ylonen) s -5 690 M -(Internet-Draft SSH Communications Security Corp) s -5 679 M -(Expires: March 31, 2004 D. Moffat, Editor, Ed.) s -5 668 M -( Sun Microsystems, Inc) s -5 657 M -( Oct 2003) s -5 624 M -( SSH Transport Layer Protocol) s -5 613 M -( draft-ietf-secsh-transport-17.txt) s -5 591 M -(Status of this Memo) s -5 569 M -( This document is an Internet-Draft and is in full conformance with) s -5 558 M -( all provisions of Section 10 of RFC2026.) s -5 536 M -( Internet-Drafts are working documents of the Internet Engineering) s -5 525 M -( Task Force \(IETF\), its areas, and its working groups. Note that other) s -5 514 M -( groups may also distribute working documents as Internet-Drafts.) s -5 492 M -( Internet-Drafts are draft documents valid for a maximum of six months) s -5 481 M -( and may be updated, replaced, or obsoleted by other documents at any) s -5 470 M -( time. It is inappropriate to use Internet-Drafts as reference) s -5 459 M -( material or to cite them other than as "work in progress.") s -5 437 M -( The list of current Internet-Drafts can be accessed at http://) s -5 426 M -( www.ietf.org/ietf/1id-abstracts.txt.) s -5 404 M -( The list of Internet-Draft Shadow Directories can be accessed at) s -5 393 M -( http://www.ietf.org/shadow.html.) s -5 371 M -( This Internet-Draft will expire on March 31, 2004.) s -5 349 M -(Copyright Notice) s -5 327 M -( Copyright \(C\) The Internet Society \(2003\). All Rights Reserved.) s -5 305 M -(Abstract) s -5 283 M -( SSH is a protocol for secure remote login and other secure network) s -5 272 M -( services over an insecure network.) s -5 250 M -( This document describes the SSH transport layer protocol which) s -5 239 M -( typically runs on top of TCP/IP. The protocol can be used as a basis) s -5 228 M -( for a number of secure network services. It provides strong) s -5 217 M -( encryption, server authentication, and integrity protection. It may) s -5 206 M -( also provide compression.) s -5 184 M -( Key exchange method, public key algorithm, symmetric encryption) s -5 173 M -( algorithm, message authentication algorithm, and hash algorithm are) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 1]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 2 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -( all negotiated.) s -5 668 M -( This document also describes the Diffie-Hellman key exchange method) s -5 657 M -( and the minimal set of algorithms that are needed to implement the) s -5 646 M -( SSH transport layer protocol.) s -5 624 M -(Table of Contents) s -5 602 M -( 1. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 3) s -5 591 M -( 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3) s -5 580 M -( 3. Conventions Used in This Document . . . . . . . . . . . . . 3) s -5 569 M -( 4. Connection Setup . . . . . . . . . . . . . . . . . . . . . . 3) s -5 558 M -( 4.1 Use over TCP/IP . . . . . . . . . . . . . . . . . . . . . . 4) s -5 547 M -( 4.2 Protocol Version Exchange . . . . . . . . . . . . . . . . . 4) s -5 536 M -( 4.3 Compatibility With Old SSH Versions . . . . . . . . . . . . 4) s -5 525 M -( 4.3.1 Old Client, New Server . . . . . . . . . . . . . . . . . . . 5) s -5 514 M -( 4.3.2 New Client, Old Server . . . . . . . . . . . . . . . . . . . 5) s -5 503 M -( 5. Binary Packet Protocol . . . . . . . . . . . . . . . . . . . 5) s -5 492 M -( 5.1 Maximum Packet Length . . . . . . . . . . . . . . . . . . . 6) s -5 481 M -( 5.2 Compression . . . . . . . . . . . . . . . . . . . . . . . . 7) s -5 470 M -( 5.3 Encryption . . . . . . . . . . . . . . . . . . . . . . . . . 7) s -5 459 M -( 5.4 Data Integrity . . . . . . . . . . . . . . . . . . . . . . . 9) s -5 448 M -( 5.5 Key Exchange Methods . . . . . . . . . . . . . . . . . . . . 10) s -5 437 M -( 5.6 Public Key Algorithms . . . . . . . . . . . . . . . . . . . 11) s -5 426 M -( 6. Key Exchange . . . . . . . . . . . . . . . . . . . . . . . . 13) s -5 415 M -( 6.1 Algorithm Negotiation . . . . . . . . . . . . . . . . . . . 13) s -5 404 M -( 6.2 Output from Key Exchange . . . . . . . . . . . . . . . . . . 16) s -5 393 M -( 6.3 Taking Keys Into Use . . . . . . . . . . . . . . . . . . . . 17) s -5 382 M -( 7. Diffie-Hellman Key Exchange . . . . . . . . . . . . . . . . 18) s -5 371 M -( 7.1 diffie-hellman-group1-sha1 . . . . . . . . . . . . . . . . . 19) s -5 360 M -( 8. Key Re-Exchange . . . . . . . . . . . . . . . . . . . . . . 20) s -5 349 M -( 9. Service Request . . . . . . . . . . . . . . . . . . . . . . 21) s -5 338 M -( 10. Additional Messages . . . . . . . . . . . . . . . . . . . . 21) s -5 327 M -( 10.1 Disconnection Message . . . . . . . . . . . . . . . . . . . 22) s -5 316 M -( 10.2 Ignored Data Message . . . . . . . . . . . . . . . . . . . . 22) s -5 305 M -( 10.3 Debug Message . . . . . . . . . . . . . . . . . . . . . . . 23) s -5 294 M -( 10.4 Reserved Messages . . . . . . . . . . . . . . . . . . . . . 23) s -5 283 M -( 11. Summary of Message Numbers . . . . . . . . . . . . . . . . . 23) s -5 272 M -( 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . 24) s -5 261 M -( 13. Security Considerations . . . . . . . . . . . . . . . . . . 24) s -5 250 M -( 14. Intellectual Property . . . . . . . . . . . . . . . . . . . 24) s -5 239 M -( 15. Additional Information . . . . . . . . . . . . . . . . . . . 24) s -5 228 M -( Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 26) s -5 217 M -( Normative . . . . . . . . . . . . . . . . . . . . . . . . . 25) s -5 206 M -( Informative . . . . . . . . . . . . . . . . . . . . . . . . 25) s -5 195 M -( A. Contibutors . . . . . . . . . . . . . . . . . . . . . . . . 27) s -5 184 M -( Intellectual Property and Copyright Statements . . . . . . . 28) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 2]) s -_R -S -PStoPSsaved restore -%%Page: (2,3) 2 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 3 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -(1. Contributors) s -5 668 M -( The major original contributors of this document were: Tatu Ylonen,) s -5 657 M -( Tero Kivinen, Timo J. Rinne, Sami Lehtinen \(all of SSH Communications) s -5 646 M -( Security Corp\), and Markku-Juhani O. Saarinen \(University of) s -5 635 M -( Jyvaskyla\)) s -5 613 M -( The document editor is: [email protected]. Comments on this) s -5 602 M -( internet draft should be sent to the IETF SECSH working group,) s -5 591 M -( details at: http://ietf.org/html.charters/secsh-charter.html) s -5 569 M -(2. Introduction) s -5 547 M -( The SSH transport layer is a secure low level transport protocol. It) s -5 536 M -( provides strong encryption, cryptographic host authentication, and) s -5 525 M -( integrity protection.) s -5 503 M -( Authentication in this protocol level is host-based; this protocol) s -5 492 M -( does not perform user authentication. A higher level protocol for) s -5 481 M -( user authentication can be designed on top of this protocol.) s -5 459 M -( The protocol has been designed to be simple, flexible, to allow) s -5 448 M -( parameter negotiation, and to minimize the number of round-trips.) s -5 437 M -( Key exchange method, public key algorithm, symmetric encryption) s -5 426 M -( algorithm, message authentication algorithm, and hash algorithm are) s -5 415 M -( all negotiated. It is expected that in most environments, only 2) s -5 404 M -( round-trips will be needed for full key exchange, server) s -5 393 M -( authentication, service request, and acceptance notification of) s -5 382 M -( service request. The worst case is 3 round-trips.) s -5 360 M -(3. Conventions Used in This Document) s -5 338 M -( The keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT",) s -5 327 M -( and "MAY" that appear in this document are to be interpreted as) s -5 316 M -( described in [RFC2119].) s -5 294 M -( The used data types and terminology are specified in the architecture) s -5 283 M -( document [SSH-ARCH].) s -5 261 M -( The architecture document also discusses the algorithm naming) s -5 250 M -( conventions that MUST be used with the SSH protocols.) s -5 228 M -(4. Connection Setup) s -5 206 M -( SSH works over any 8-bit clean, binary-transparent transport. The) s -5 195 M -( underlying transport SHOULD protect against transmission errors as) s -5 184 M -( such errors cause the SSH connection to terminate.) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 3]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 4 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -( The client initiates the connection.) s -5 668 M -(4.1 Use over TCP/IP) s -5 646 M -( When used over TCP/IP, the server normally listens for connections on) s -5 635 M -( port 22. This port number has been registered with the IANA, and has) s -5 624 M -( been officially assigned for SSH.) s -5 602 M -(4.2 Protocol Version Exchange) s -5 580 M -( When the connection has been established, both sides MUST send an) s -5 569 M -( identification string of the form "SSH-protoversion-softwareversion) s -5 558 M -( comments", followed by carriage return and newline characters \(ASCII) s -5 547 M -( 13 and 10, respectively\). Both sides MUST be able to process) s -5 536 M -( identification strings without carriage return character. No null) s -5 525 M -( character is sent. The maximum length of the string is 255) s -5 514 M -( characters, including the carriage return and newline.) s -5 492 M -( The part of the identification string preceding carriage return and) s -5 481 M -( newline is used in the Diffie-Hellman key exchange \(see Section) s -5 470 M -( Section 7\).) s -5 448 M -( The server MAY send other lines of data before sending the version) s -5 437 M -( string. Each line SHOULD be terminated by a carriage return and) s -5 426 M -( newline. Such lines MUST NOT begin with "SSH-", and SHOULD be) s -5 415 M -( encoded in ISO-10646 UTF-8 [RFC2279] \(language is not specified\).) s -5 404 M -( Clients MUST be able to process such lines; they MAY be silently) s -5 393 M -( ignored, or MAY be displayed to the client user; if they are) s -5 382 M -( displayed, control character filtering discussed in [SSH-ARCH] SHOULD) s -5 371 M -( be used. The primary use of this feature is to allow TCP-wrappers to) s -5 360 M -( display an error message before disconnecting.) s -5 338 M -( Version strings MUST consist of printable US-ASCII characters, not) s -5 327 M -( including whitespaces or a minus sign \(-\). The version string is) s -5 316 M -( primarily used to trigger compatibility extensions and to indicate) s -5 305 M -( the capabilities of an implementation. The comment string should) s -5 294 M -( contain additional information that might be useful in solving user) s -5 283 M -( problems.) s -5 261 M -( The protocol version described in this document is 2.0.) s -5 239 M -( Key exchange will begin immediately after sending this identifier.) s -5 228 M -( All packets following the identification string SHALL use the binary) s -5 217 M -( packet protocol, to be described below.) s -5 195 M -(4.3 Compatibility With Old SSH Versions) s -5 173 M -( During the transition period, it is important to be able to work in a) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 4]) s -_R -S -PStoPSsaved restore -%%Page: (4,5) 3 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 5 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -( way that is compatible with the installed SSH clients and servers) s -5 679 M -( that use an older version of the protocol. Information in this) s -5 668 M -( section is only relevant for implementations supporting compatibility) s -5 657 M -( with SSH versions 1.x. There is no standards track or informational) s -5 646 M -( draft available that defines the SSH 1.x protocol. The only known) s -5 635 M -( documentation of the 1.x protocol is contained in README files that) s -5 624 M -( are shipped along with the source code.) s -5 602 M -(4.3.1 Old Client, New Server) s -5 580 M -( Server implementations MAY support a configurable "compatibility") s -5 569 M -( flag that enables compatibility with old versions. When this flag is) s -5 558 M -( on, the server SHOULD identify its protocol version as "1.99".) s -5 547 M -( Clients using protocol 2.0 MUST be able to identify this as identical) s -5 536 M -( to "2.0". In this mode the server SHOULD NOT send the carriage) s -5 525 M -( return character \(ASCII 13\) after the version identification string.) s -5 503 M -( In the compatibility mode the server SHOULD NOT send any further data) s -5 492 M -( after its initialization string until it has received an) s -5 481 M -( identification string from the client. The server can then determine) s -5 470 M -( whether the client is using an old protocol, and can revert to the) s -5 459 M -( old protocol if required. In the compatibility mode, the server MUST) s -5 448 M -( NOT send additional data before the version string.) s -5 426 M -( When compatibility with old clients is not needed, the server MAY) s -5 415 M -( send its initial key exchange data immediately after the) s -5 404 M -( identification string.) s -5 382 M -(4.3.2 New Client, Old Server) s -5 360 M -( Since the new client MAY immediately send additional data after its) s -5 349 M -( identification string \(before receiving server's identification\), the) s -5 338 M -( old protocol may already have been corrupted when the client learns) s -5 327 M -( that the server is old. When this happens, the client SHOULD close) s -5 316 M -( the connection to the server, and reconnect using the old protocol.) s -5 294 M -(5. Binary Packet Protocol) s -5 272 M -( Each packet is in the following format:) s -5 250 M -( uint32 packet_length) s -5 239 M -( byte padding_length) s -5 228 M -( byte[n1] payload; n1 = packet_length - padding_length - 1) s -5 217 M -( byte[n2] random padding; n2 = padding_length) s -5 206 M -( byte[m] mac \(message authentication code\); m = mac_length) s -5 184 M -( packet_length) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 5]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 6 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -( The length of the packet \(bytes\), not including MAC or the) s -5 679 M -( packet_length field itself.) s -5 657 M -( padding_length) s -5 646 M -( Length of padding \(bytes\).) s -5 624 M -( payload) s -5 613 M -( The useful contents of the packet. If compression has been) s -5 602 M -( negotiated, this field is compressed. Initially, compression) s -5 591 M -( MUST be "none".) s -5 569 M -( random padding) s -5 558 M -( Arbitrary-length padding, such that the total length of) s -5 547 M -( \(packet_length || padding_length || payload || padding\) is a) s -5 536 M -( multiple of the cipher block size or 8, whichever is larger.) s -5 525 M -( There MUST be at least four bytes of padding. The padding) s -5 514 M -( SHOULD consist of random bytes. The maximum amount of padding) s -5 503 M -( is 255 bytes.) s -5 481 M -( mac) s -5 470 M -( Message authentication code. If message authentication has) s -5 459 M -( been negotiated, this field contains the MAC bytes. Initially,) s -5 448 M -( the MAC algorithm MUST be "none".) s -5 415 M -( Note that length of the concatenation of packet length, padding) s -5 404 M -( length, payload, and padding MUST be a multiple of the cipher block) s -5 393 M -( size or 8, whichever is larger. This constraint MUST be enforced) s -5 382 M -( even when using stream ciphers. Note that the packet length field is) s -5 371 M -( also encrypted, and processing it requires special care when sending) s -5 360 M -( or receiving packets.) s -5 338 M -( The minimum size of a packet is 16 \(or the cipher block size,) s -5 327 M -( whichever is larger\) bytes \(plus MAC\); implementations SHOULD decrypt) s -5 316 M -( the length after receiving the first 8 \(or cipher block size,) s -5 305 M -( whichever is larger\) bytes of a packet.) s -5 283 M -(5.1 Maximum Packet Length) s -5 261 M -( All implementations MUST be able to process packets with uncompressed) s -5 250 M -( payload length of 32768 bytes or less and total packet size of 35000) s -5 239 M -( bytes or less \(including length, padding length, payload, padding,) s -5 228 M -( and MAC.\). The maximum of 35000 bytes is an arbitrary chosen value) s -5 217 M -( larger than uncompressed size. Implementations SHOULD support longer) s -5 206 M -( packets, where they might be needed, e.g. if an implementation wants) s -5 195 M -( to send a very large number of certificates. Such packets MAY be) s -5 184 M -( sent if the version string indicates that the other party is able to) s -5 173 M -( process them. However, implementations SHOULD check that the packet) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 6]) s -_R -S -PStoPSsaved restore -%%Page: (6,7) 4 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 7 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -( length is reasonable for the implementation to avoid) s -5 679 M -( denial-of-service and/or buffer overflow attacks.) s -5 657 M -(5.2 Compression) s -5 635 M -( If compression has been negotiated, the payload field \(and only it\)) s -5 624 M -( will be compressed using the negotiated algorithm. The length field) s -5 613 M -( and MAC will be computed from the compressed payload. Encryption will) s -5 602 M -( be done after compression.) s -5 580 M -( Compression MAY be stateful, depending on the method. Compression) s -5 569 M -( MUST be independent for each direction, and implementations MUST) s -5 558 M -( allow independently choosing the algorithm for each direction.) s -5 536 M -( The following compression methods are currently defined:) s -5 514 M -( none REQUIRED no compression) s -5 503 M -( zlib OPTIONAL ZLIB \(LZ77\) compression) s -5 481 M -( The "zlib" compression is described in [RFC1950] and in [RFC1951].) s -5 470 M -( The compression context is initialized after each key exchange, and) s -5 459 M -( is passed from one packet to the next with only a partial flush being) s -5 448 M -( performed at the end of each packet. A partial flush means that the) s -5 437 M -( current compressed block is ended and all data will be output. If the) s -5 426 M -( current block is not a stored block, one or more empty blocks are) s -5 415 M -( added after the current block to ensure that there are at least 8) s -5 404 M -( bits counting from the start of the end-of-block code of the current) s -5 393 M -( block to the end of the packet payload.) s -5 371 M -( Additional methods may be defined as specified in [SSH-ARCH].) s -5 349 M -(5.3 Encryption) s -5 327 M -( An encryption algorithm and a key will be negotiated during the key) s -5 316 M -( exchange. When encryption is in effect, the packet length, padding) s -5 305 M -( length, payload and padding fields of each packet MUST be encrypted) s -5 294 M -( with the given algorithm.) s -5 272 M -( The encrypted data in all packets sent in one direction SHOULD be) s -5 261 M -( considered a single data stream. For example, initialization vectors) s -5 250 M -( SHOULD be passed from the end of one packet to the beginning of the) s -5 239 M -( next packet. All ciphers SHOULD use keys with an effective key length) s -5 228 M -( of 128 bits or more.) s -5 206 M -( The ciphers in each direction MUST run independently of each other,) s -5 195 M -( and implementations MUST allow independently choosing the algorithm) s -5 184 M -( for each direction \(if multiple algorithms are allowed by local) s -5 173 M -( policy\).) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 7]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 8 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -( The following ciphers are currently defined:) s -5 668 M -( 3des-cbc REQUIRED three-key 3DES in CBC mode) s -5 657 M -( blowfish-cbc OPTIONALi Blowfish in CBC mode) s -5 646 M -( twofish256-cbc OPTIONAL Twofish in CBC mode,) s -5 635 M -( with 256-bit key) s -5 624 M -( twofish-cbc OPTIONAL alias for "twofish256-cbc" \(this) s -5 613 M -( is being retained for) s -5 602 M -( historical reasons\)) s -5 591 M -( twofish192-cbc OPTIONAL Twofish with 192-bit key) s -5 580 M -( twofish128-cbc OPTIONAL Twofish with 128-bit key) s -5 569 M -( aes256-cbc OPTIONAL AES \(Rijndael\) in CBC mode,) s -5 558 M -( with 256-bit key) s -5 547 M -( aes192-cbc OPTIONAL AES with 192-bit key) s -5 536 M -( aes128-cbc RECOMMENDED AES with 128-bit key) s -5 525 M -( serpent256-cbc OPTIONAL Serpent in CBC mode, with) s -5 514 M -( 256-bit key) s -5 503 M -( serpent192-cbc OPTIONAL Serpent with 192-bit key) s -5 492 M -( serpent128-cbc OPTIONAL Serpent with 128-bit key) s -5 481 M -( arcfour OPTIONAL the ARCFOUR stream cipher) s -5 470 M -( idea-cbc OPTIONAL IDEA in CBC mode) s -5 459 M -( cast128-cbc OPTIONAL CAST-128 in CBC mode) s -5 448 M -( none OPTIONAL no encryption; NOT RECOMMENDED) s -5 426 M -( The "3des-cbc" cipher is three-key triple-DES) s -5 415 M -( \(encrypt-decrypt-encrypt\), where the first 8 bytes of the key are) s -5 404 M -( used for the first encryption, the next 8 bytes for the decryption,) s -5 393 M -( and the following 8 bytes for the final encryption. This requires 24) s -5 382 M -( bytes of key data \(of which 168 bits are actually used\). To) s -5 371 M -( implement CBC mode, outer chaining MUST be used \(i.e., there is only) s -5 360 M -( one initialization vector\). This is a block cipher with 8 byte) s -5 349 M -( blocks. This algorithm is defined in [FIPS-46-3]) s -5 327 M -( The "blowfish-cbc" cipher is Blowfish in CBC mode, with 128 bit keys) s -5 316 M -( [SCHNEIER]. This is a block cipher with 8 byte blocks.) s -5 294 M -( The "twofish-cbc" or "twofish256-cbc" cipher is Twofish in CBC mode,) s -5 283 M -( with 256 bit keys as described [TWOFISH]. This is a block cipher with) s -5 272 M -( 16 byte blocks.) s -5 250 M -( The "twofish192-cbc" cipher. Same as above but with 192-bit key.) s -5 228 M -( The "twofish128-cbc" cipher. Same as above but with 128-bit key.) s -5 206 M -( The "aes256-cbc" cipher is AES \(Advanced Encryption Standard\)) s -5 195 M -( [FIPS-197], formerly Rijndael, in CBC mode. This version uses 256-bit) s -5 184 M -( key.) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 8]) s -_R -S -PStoPSsaved restore -%%Page: (8,9) 5 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 9 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -( The "aes192-cbc" cipher. Same as above but with 192-bit key.) s -5 668 M -( The "aes128-cbc" cipher. Same as above but with 128-bit key.) s -5 646 M -( The "serpent256-cbc" cipher in CBC mode, with 256-bit key as) s -5 635 M -( described in the Serpent AES submission.) s -5 613 M -( The "serpent192-cbc" cipher. Same as above but with 192-bit key.) s -5 591 M -( The "serpent128-cbc" cipher. Same as above but with 128-bit key.) s -5 569 M -( The "arcfour" is the Arcfour stream cipher with 128 bit keys. The) s -5 558 M -( Arcfour cipher is believed to be compatible with the RC4 cipher) s -5 547 M -( [SCHNEIER]. RC4 is a registered trademark of RSA Data Security Inc.) s -5 536 M -( Arcfour \(and RC4\) has problems with weak keys, and should be used) s -5 525 M -( with caution.) s -5 503 M -( The "idea-cbc" cipher is the IDEA cipher in CBC mode [SCHNEIER].) s -5 481 M -( The "cast128-cbc" cipher is the CAST-128 cipher in CBC mode) s -5 470 M -( [RFC2144].) s -5 448 M -( The "none" algorithm specifies that no encryption is to be done.) s -5 437 M -( Note that this method provides no confidentiality protection, and it) s -5 426 M -( is not recommended. Some functionality \(e.g. password) s -5 415 M -( authentication\) may be disabled for security reasons if this cipher) s -5 404 M -( is chosen.) s -5 382 M -( Additional methods may be defined as specified in [SSH-ARCH].) s -5 360 M -(5.4 Data Integrity) s -5 338 M -( Data integrity is protected by including with each packet a message) s -5 327 M -( authentication code \(MAC\) that is computed from a shared secret,) s -5 316 M -( packet sequence number, and the contents of the packet.) s -5 294 M -( The message authentication algorithm and key are negotiated during) s -5 283 M -( key exchange. Initially, no MAC will be in effect, and its length) s -5 272 M -( MUST be zero. After key exchange, the selected MAC will be computed) s -5 261 M -( before encryption from the concatenation of packet data:) s -5 239 M -( mac = MAC\(key, sequence_number || unencrypted_packet\)) s -5 217 M -( where unencrypted_packet is the entire packet without MAC \(the length) s -5 206 M -( fields, payload and padding\), and sequence_number is an implicit) s -5 195 M -( packet sequence number represented as uint32. The sequence number is) s -5 184 M -( initialized to zero for the first packet, and is incremented after) s -5 173 M -( every packet \(regardless of whether encryption or MAC is in use\). It) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 9]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 10 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -( is never reset, even if keys/algorithms are renegotiated later. It) s -5 679 M -( wraps around to zero after every 2^32 packets. The packet sequence) s -5 668 M -( number itself is not included in the packet sent over the wire.) s -5 646 M -( The MAC algorithms for each direction MUST run independently, and) s -5 635 M -( implementations MUST allow choosing the algorithm independently for) s -5 624 M -( both directions.) s -5 602 M -( The MAC bytes resulting from the MAC algorithm MUST be transmitted) s -5 591 M -( without encryption as the last part of the packet. The number of MAC) s -5 580 M -( bytes depends on the algorithm chosen.) s -5 558 M -( The following MAC algorithms are currently defined:) s -5 536 M -( hmac-sha1 REQUIRED HMAC-SHA1 \(digest length = key) s -5 525 M -( length = 20\)) s -5 514 M -( hmac-sha1-96 RECOMMENDED first 96 bits of HMAC-SHA1 \(digest) s -5 503 M -( length = 12, key length = 20\)) s -5 492 M -( hmac-md5 OPTIONAL HMAC-MD5 \(digest length = key) s -5 481 M -( length = 16\)) s -5 470 M -( hmac-md5-96 OPTIONAL first 96 bits of HMAC-MD5 \(digest) s -5 459 M -( length = 12, key length = 16\)) s -5 448 M -( none OPTIONAL no MAC; NOT RECOMMENDED) s -5 426 M -( Figure 1) s -5 404 M -( The "hmac-*" algorithms are described in [RFC2104] The "*-n" MACs use) s -5 393 M -( only the first n bits of the resulting value.) s -5 371 M -( The hash algorithms are described in [SCHNEIER].) s -5 349 M -( Additional methods may be defined as specified in [SSH-ARCH].) s -5 327 M -(5.5 Key Exchange Methods) s -5 305 M -( The key exchange method specifies how one-time session keys are) s -5 294 M -( generated for encryption and for authentication, and how the server) s -5 283 M -( authentication is done.) s -5 261 M -( Only one REQUIRED key exchange method has been defined:) s -5 239 M -( diffie-hellman-group1-sha1 REQUIRED) s -5 217 M -( This method is described later in this document.) s -5 195 M -( Additional methods may be defined as specified in [SSH-ARCH].) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 10]) s -_R -S -PStoPSsaved restore -%%Page: (10,11) 6 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 11 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -(5.6 Public Key Algorithms) s -5 668 M -( This protocol has been designed to be able to operate with almost any) s -5 657 M -( public key format, encoding, and algorithm \(signature and/or) s -5 646 M -( encryption\).) s -5 624 M -( There are several aspects that define a public key type:) s -5 613 M -( o Key format: how is the key encoded and how are certificates) s -5 602 M -( represented. The key blobs in this protocol MAY contain) s -5 591 M -( certificates in addition to keys.) s -5 580 M -( o Signature and/or encryption algorithms. Some key types may not) s -5 569 M -( support both signing and encryption. Key usage may also be) s -5 558 M -( restricted by policy statements in e.g. certificates. In this) s -5 547 M -( case, different key types SHOULD be defined for the different) s -5 536 M -( policy alternatives.) s -5 525 M -( o Encoding of signatures and/or encrypted data. This includes but is) s -5 514 M -( not limited to padding, byte order, and data formats.) s -5 492 M -( The following public key and/or certificate formats are currently defined:) s -5 470 M -( ssh-dss REQUIRED sign Raw DSS Key) s -5 459 M -( ssh-rsa RECOMMENDED sign Raw RSA Key) s -5 448 M -( x509v3-sign-rsa OPTIONAL sign X.509 certificates \(RSA key\)) s -5 437 M -( x509v3-sign-dss OPTIONAL sign X.509 certificates \(DSS key\)) s -5 426 M -( spki-sign-rsa OPTIONAL sign SPKI certificates \(RSA key\)) s -5 415 M -( spki-sign-dss OPTIONAL sign SPKI certificates \(DSS key\)) s -5 404 M -( pgp-sign-rsa OPTIONAL sign OpenPGP certificates \(RSA key\)) s -5 393 M -( pgp-sign-dss OPTIONAL sign OpenPGP certificates \(DSS key\)) s -5 371 M -( Additional key types may be defined as specified in [SSH-ARCH].) s -5 349 M -( The key type MUST always be explicitly known \(from algorithm) s -5 338 M -( negotiation or some other source\). It is not normally included in) s -5 327 M -( the key blob.) s -5 305 M -( Certificates and public keys are encoded as follows:) s -5 283 M -( string certificate or public key format identifier) s -5 272 M -( byte[n] key/certificate data) s -5 250 M -( The certificate part may have be a zero length string, but a public) s -5 239 M -( key is required. This is the public key that will be used for) s -5 228 M -( authentication; the certificate sequence contained in the certificate) s -5 217 M -( blob can be used to provide authorization.) s -5 195 M -( Public key / certifcate formats that do not explicitly specify a) s -5 184 M -( signature format identifier MUST use the public key / certificate) s -5 173 M -( format identifier as the signature identifier.) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 11]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 12 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -( Signatures are encoded as follows:) s -5 679 M -( string signature format identifier \(as specified by the) s -5 668 M -( public key / cert format\)) s -5 657 M -( byte[n] signature blob in format specific encoding.) s -5 624 M -( The "ssh-dss" key format has the following specific encoding:) s -5 602 M -( string "ssh-dss") s -5 591 M -( mpint p) s -5 580 M -( mpint q) s -5 569 M -( mpint g) s -5 558 M -( mpint y) s -5 536 M -( Here the p, q, g, and y parameters form the signature key blob.) s -5 514 M -( Signing and verifying using this key format is done according to the) s -5 503 M -( Digital Signature Standard [FIPS-186] using the SHA-1 hash. A) s -5 492 M -( description can also be found in [SCHNEIER].) s -5 470 M -( The resulting signature is encoded as follows:) s -5 448 M -( string "ssh-dss") s -5 437 M -( string dss_signature_blob) s -5 415 M -( dss_signature_blob is encoded as a string containing r followed by s) s -5 404 M -( \(which are 160 bits long integers, without lengths or padding,) s -5 393 M -( unsigned and in network byte order\).) s -5 371 M -( The "ssh-rsa" key format has the following specific encoding:) s -5 349 M -( string "ssh-rsa") s -5 338 M -( mpint e) s -5 327 M -( mpint n) s -5 305 M -( Here the e and n parameters form the signature key blob.) s -5 283 M -( Signing and verifying using this key format is done according to) s -5 272 M -( [SCHNEIER] and [PKCS1] using the SHA-1 hash.) s -5 250 M -( The resulting signature is encoded as follows:) s -5 228 M -( string "ssh-rsa") s -5 217 M -( string rsa_signature_blob) s -5 195 M -( rsa_signature_blob is encoded as a string containing s \(which is an) s -5 184 M -( integer, without lengths or padding, unsigned and in network byte) s -5 173 M -( order\).) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 12]) s -_R -S -PStoPSsaved restore -%%Page: (12,13) 7 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 13 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -( The "spki-sign-rsa" method indicates that the certificate blob) s -5 679 M -( contains a sequence of SPKI certificates. The format of SPKI) s -5 668 M -( certificates is described in [RFC2693]. This method indicates that) s -5 657 M -( the key \(or one of the keys in the certificate\) is an RSA-key.) s -5 635 M -( The "spki-sign-dss". As above, but indicates that the key \(or one of) s -5 624 M -( the keys in the certificate\) is a DSS-key.) s -5 602 M -( The "pgp-sign-rsa" method indicates the certificates, the public key,) s -5 591 M -( and the signature are in OpenPGP compatible binary format) s -5 580 M -( \([RFC2440]\). This method indicates that the key is an RSA-key.) s -5 558 M -( The "pgp-sign-dss". As above, but indicates that the key is a) s -5 547 M -( DSS-key.) s -5 525 M -(6. Key Exchange) s -5 503 M -( Key exchange begins by each side sending lists of supported) s -5 492 M -( algorithms. Each side has a preferred algorithm in each category, and) s -5 481 M -( it is assumed that most implementations at any given time will use) s -5 470 M -( the same preferred algorithm. Each side MAY guess which algorithm) s -5 459 M -( the other side is using, and MAY send an initial key exchange packet) s -5 448 M -( according to the algorithm if appropriate for the preferred method.) s -5 426 M -( Guess is considered wrong, if:) s -5 415 M -( o the kex algorithm and/or the host key algorithm is guessed wrong) s -5 404 M -( \(server and client have different preferred algorithm\), or) s -5 393 M -( o if any of the other algorithms cannot be agreed upon \(the) s -5 382 M -( procedure is defined below in Section Section 6.1\).) s -5 360 M -( Otherwise, the guess is considered to be right and the optimistically) s -5 349 M -( sent packet MUST be handled as the first key exchange packet.) s -5 327 M -( However, if the guess was wrong, and a packet was optimistically sent) s -5 316 M -( by one or both parties, such packets MUST be ignored \(even if the) s -5 305 M -( error in the guess would not affect the contents of the initial) s -5 294 M -( packet\(s\)\), and the appropriate side MUST send the correct initial) s -5 283 M -( packet.) s -5 261 M -( Server authentication in the key exchange MAY be implicit. After a) s -5 250 M -( key exchange with implicit server authentication, the client MUST) s -5 239 M -( wait for response to its service request message before sending any) s -5 228 M -( further data.) s -5 206 M -(6.1 Algorithm Negotiation) s -5 184 M -( Key exchange begins by each side sending the following packet:) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 13]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 14 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -( byte SSH_MSG_KEXINIT) s -5 679 M -( byte[16] cookie \(random bytes\)) s -5 668 M -( string kex_algorithms) s -5 657 M -( string server_host_key_algorithms) s -5 646 M -( string encryption_algorithms_client_to_server) s -5 635 M -( string encryption_algorithms_server_to_client) s -5 624 M -( string mac_algorithms_client_to_server) s -5 613 M -( string mac_algorithms_server_to_client) s -5 602 M -( string compression_algorithms_client_to_server) s -5 591 M -( string compression_algorithms_server_to_client) s -5 580 M -( string languages_client_to_server) s -5 569 M -( string languages_server_to_client) s -5 558 M -( boolean first_kex_packet_follows) s -5 547 M -( uint32 0 \(reserved for future extension\)) s -5 525 M -( Each of the algorithm strings MUST be a comma-separated list of) s -5 514 M -( algorithm names \(see ''Algorithm Naming'' in [SSH-ARCH]\). Each) s -5 503 M -( supported \(allowed\) algorithm MUST be listed in order of preference.) s -5 481 M -( The first algorithm in each list MUST be the preferred \(guessed\)) s -5 470 M -( algorithm. Each string MUST contain at least one algorithm name.) s -5 437 M -( cookie) s -5 426 M -( The cookie MUST be a random value generated by the sender. Its) s -5 415 M -( purpose is to make it impossible for either side to fully) s -5 404 M -( determine the keys and the session identifier.) s -5 382 M -( kex_algorithms) s -5 371 M -( Key exchange algorithms were defined above. The first) s -5 360 M -( algorithm MUST be the preferred \(and guessed\) algorithm. If) s -5 349 M -( both sides make the same guess, that algorithm MUST be used.) s -5 338 M -( Otherwise, the following algorithm MUST be used to choose a key) s -5 327 M -( exchange method: iterate over client's kex algorithms, one at a) s -5 316 M -( time. Choose the first algorithm that satisfies the following) s -5 305 M -( conditions:) s -5 294 M -( + the server also supports the algorithm,) s -5 283 M -( + if the algorithm requires an encryption-capable host key,) s -5 272 M -( there is an encryption-capable algorithm on the server's) s -5 261 M -( server_host_key_algorithms that is also supported by the) s -5 250 M -( client, and) s -5 239 M -( + if the algorithm requires a signature-capable host key,) s -5 228 M -( there is a signature-capable algorithm on the server's) s -5 217 M -( server_host_key_algorithms that is also supported by the) s -5 206 M -( client.) s -5 195 M -( + If no algorithm satisfying all these conditions can be) s -5 184 M -( found, the connection fails, and both sides MUST disconnect.) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 14]) s -_R -S -PStoPSsaved restore -%%Page: (14,15) 8 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 15 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -( server_host_key_algorithms) s -5 679 M -( List of the algorithms supported for the server host key. The) s -5 668 M -( server lists the algorithms for which it has host keys; the) s -5 657 M -( client lists the algorithms that it is willing to accept.) s -5 646 M -( \(There MAY be multiple host keys for a host, possibly with) s -5 635 M -( different algorithms.\)) s -5 613 M -( Some host keys may not support both signatures and encryption) s -5 602 M -( \(this can be determined from the algorithm\), and thus not all) s -5 591 M -( host keys are valid for all key exchange methods.) s -5 569 M -( Algorithm selection depends on whether the chosen key exchange) s -5 558 M -( algorithm requires a signature or encryption capable host key.) s -5 547 M -( It MUST be possible to determine this from the public key) s -5 536 M -( algorithm name. The first algorithm on the client's list that) s -5 525 M -( satisfies the requirements and is also supported by the server) s -5 514 M -( MUST be chosen. If there is no such algorithm, both sides MUST) s -5 503 M -( disconnect.) s -5 481 M -( encryption_algorithms) s -5 470 M -( Lists the acceptable symmetric encryption algorithms in order) s -5 459 M -( of preference. The chosen encryption algorithm to each) s -5 448 M -( direction MUST be the first algorithm on the client's list) s -5 437 M -( that is also on the server's list. If there is no such) s -5 426 M -( algorithm, both sides MUST disconnect.) s -5 404 M -( Note that "none" must be explicitly listed if it is to be) s -5 393 M -( acceptable. The defined algorithm names are listed in Section) s -5 382 M -( Section 5.3.) s -5 360 M -( mac_algorithms) s -5 349 M -( Lists the acceptable MAC algorithms in order of preference.) s -5 338 M -( The chosen MAC algorithm MUST be the first algorithm on the) s -5 327 M -( client's list that is also on the server's list. If there is) s -5 316 M -( no such algorithm, both sides MUST disconnect.) s -5 294 M -( Note that "none" must be explicitly listed if it is to be) s -5 283 M -( acceptable. The MAC algorithm names are listed in Section) s -5 272 M -( Figure 1.) s -5 250 M -( compression_algorithms) s -5 239 M -( Lists the acceptable compression algorithms in order of) s -5 228 M -( preference. The chosen compression algorithm MUST be the first) s -5 217 M -( algorithm on the client's list that is also on the server's) s -5 206 M -( list. If there is no such algorithm, both sides MUST) s -5 195 M -( disconnect.) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 15]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 16 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -( Note that "none" must be explicitly listed if it is to be) s -5 679 M -( acceptable. The compression algorithm names are listed in) s -5 668 M -( Section Section 5.2.) s -5 646 M -( languages) s -5 635 M -( This is a comma-separated list of language tags in order of) s -5 624 M -( preference [RFC3066]. Both parties MAY ignore this list. If) s -5 613 M -( there are no language preferences, this list SHOULD be empty.) s -5 602 M -( Language tags SHOULD NOT be present unless they are known to be) s -5 591 M -( needed by the sending party.) s -5 569 M -( first_kex_packet_follows) s -5 558 M -( Indicates whether a guessed key exchange packet follows. If a) s -5 547 M -( guessed packet will be sent, this MUST be TRUE. If no guessed) s -5 536 M -( packet will be sent, this MUST be FALSE.) s -5 514 M -( After receiving the SSH_MSG_KEXINIT packet from the other side,) s -5 503 M -( each party will know whether their guess was right. If the) s -5 492 M -( other party's guess was wrong, and this field was TRUE, the) s -5 481 M -( next packet MUST be silently ignored, and both sides MUST then) s -5 470 M -( act as determined by the negotiated key exchange method. If) s -5 459 M -( the guess was right, key exchange MUST continue using the) s -5 448 M -( guessed packet.) s -5 426 M -( After the KEXINIT packet exchange, the key exchange algorithm is run.) s -5 415 M -( It may involve several packet exchanges, as specified by the key) s -5 404 M -( exchange method.) s -5 382 M -(6.2 Output from Key Exchange) s -5 360 M -( The key exchange produces two values: a shared secret K, and an) s -5 349 M -( exchange hash H. Encryption and authentication keys are derived from) s -5 338 M -( these. The exchange hash H from the first key exchange is) s -5 327 M -( additionally used as the session identifier, which is a unique) s -5 316 M -( identifier for this connection. It is used by authentication methods) s -5 305 M -( as a part of the data that is signed as a proof of possession of a) s -5 294 M -( private key. Once computed, the session identifier is not changed,) s -5 283 M -( even if keys are later re-exchanged.) s -5 250 M -( Each key exchange method specifies a hash function that is used in) s -5 239 M -( the key exchange. The same hash algorithm MUST be used in key) s -5 228 M -( derivation. Here, we'll call it HASH.) s -5 195 M -( Encryption keys MUST be computed as HASH of a known value and K as) s -5 184 M -( follows:) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 16]) s -_R -S -PStoPSsaved restore -%%Page: (16,17) 9 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 17 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -( o Initial IV client to server: HASH\(K || H || "A" || session_id\)) s -5 679 M -( \(Here K is encoded as mpint and "A" as byte and session_id as raw) s -5 668 M -( data."A" means the single character A, ASCII 65\).) s -5 657 M -( o Initial IV server to client: HASH\(K || H || "B" || session_id\)) s -5 646 M -( o Encryption key client to server: HASH\(K || H || "C" || session_id\)) s -5 635 M -( o Encryption key server to client: HASH\(K || H || "D" || session_id\)) s -5 624 M -( o Integrity key client to server: HASH\(K || H || "E" || session_id\)) s -5 613 M -( o Integrity key server to client: HASH\(K || H || "F" || session_id\)) s -5 591 M -( Key data MUST be taken from the beginning of the hash output. 128) s -5 580 M -( bits \(16 bytes\) MUST be used for algorithms with variable-length) s -5 569 M -( keys. The only variable key length algorithm defined in this document) s -5 558 M -( is arcfour\). For other algorithms, as many bytes as are needed are) s -5 547 M -( taken from the beginning of the hash value. If the key length needed) s -5 536 M -( is longer than the output of the HASH, the key is extended by) s -5 525 M -( computing HASH of the concatenation of K and H and the entire key so) s -5 514 M -( far, and appending the resulting bytes \(as many as HASH generates\) to) s -5 503 M -( the key. This process is repeated until enough key material is) s -5 492 M -( available; the key is taken from the beginning of this value. In) s -5 481 M -( other words:) s -5 459 M -( K1 = HASH\(K || H || X || session_id\) \(X is e.g. "A"\)) s -5 448 M -( K2 = HASH\(K || H || K1\)) s -5 437 M -( K3 = HASH\(K || H || K1 || K2\)) s -5 426 M -( ...) s -5 415 M -( key = K1 || K2 || K3 || ...) s -5 393 M -( This process will lose entropy if the amount of entropy in K is) s -5 382 M -( larger than the internal state size of HASH.) s -5 360 M -(6.3 Taking Keys Into Use) s -5 338 M -( Key exchange ends by each side sending an SSH_MSG_NEWKEYS message.) s -5 327 M -( This message is sent with the old keys and algorithms. All messages) s -5 316 M -( sent after this message MUST use the new keys and algorithms.) s -5 283 M -( When this message is received, the new keys and algorithms MUST be) s -5 272 M -( taken into use for receiving.) s -5 239 M -( This message is the only valid message after key exchange, in) s -5 228 M -( addition to SSH_MSG_DEBUG, SSH_MSG_DISCONNECT and SSH_MSG_IGNORE) s -5 217 M -( messages. The purpose of this message is to ensure that a party is) s -5 206 M -( able to respond with a disconnect message that the other party can) s -5 195 M -( understand if something goes wrong with the key exchange.) s -5 184 M -( Implementations MUST NOT accept any other messages after key exchange) s -5 173 M -( before receiving SSH_MSG_NEWKEYS.) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 17]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 18 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -( byte SSH_MSG_NEWKEYS) s -5 657 M -(7. Diffie-Hellman Key Exchange) s -5 635 M -( The Diffie-Hellman key exchange provides a shared secret that can not) s -5 624 M -( be determined by either party alone. The key exchange is combined) s -5 613 M -( with a signature with the host key to provide host authentication.) s -5 580 M -( In the following description \(C is the client, S is the server; p is) s -5 569 M -( a large safe prime, g is a generator for a subgroup of GF\(p\), and q) s -5 558 M -( is the order of the subgroup; V_S is S's version string; V_C is C's) s -5 547 M -( version string; K_S is S's public host key; I_C is C's KEXINIT) s -5 536 M -( message and I_S S's KEXINIT message which have been exchanged before) s -5 525 M -( this part begins\):) s -5 492 M -( 1. C generates a random number x \(1 < x < q\) and computes e = g^x) s -5 481 M -( mod p. C sends "e" to S.) s -5 459 M -( 2. S generates a random number y \(0 < y < q\) and computes f = g^y) s -5 448 M -( mod p. S receives "e". It computes K = e^y mod p, H = hash\(V_C) s -5 437 M -( || V_S || I_C || I_S || K_S || e || f || K\) \(these elements are) s -5 426 M -( encoded according to their types; see below\), and signature s on) s -5 415 M -( H with its private host key. S sends "K_S || f || s" to C. The) s -5 404 M -( signing operation may involve a second hashing operation.) s -5 382 M -( 3. C verifies that K_S really is the host key for S \(e.g. using) s -5 371 M -( certificates or a local database\). C is also allowed to accept) s -5 360 M -( the key without verification; however, doing so will render the) s -5 349 M -( protocol insecure against active attacks \(but may be desirable) s -5 338 M -( for practical reasons in the short term in many environments\). C) s -5 327 M -( then computes K = f^x mod p, H = hash\(V_C || V_S || I_C || I_S ||) s -5 316 M -( K_S || e || f || K\), and verifies the signature s on H.) s -5 294 M -( Either side MUST NOT send or accept e or f values that are not in the) s -5 283 M -( range [1, p-1]. If this condition is violated, the key exchange) s -5 272 M -( fails.) s -5 239 M -( This is implemented with the following messages. The hash algorithm) s -5 228 M -( for computing the exchange hash is defined by the method name, and is) s -5 217 M -( called HASH. The public key algorithm for signing is negotiated with) s -5 206 M -( the KEXINIT messages.) s -5 184 M -( First, the client sends the following:) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 18]) s -_R -S -PStoPSsaved restore -%%Page: (18,19) 10 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 19 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -( byte SSH_MSG_KEXDH_INIT) s -5 679 M -( mpint e) s -5 646 M -( The server responds with the following:) s -5 624 M -( byte SSH_MSG_KEXDH_REPLY) s -5 613 M -( string server public host key and certificates \(K_S\)) s -5 602 M -( mpint f) s -5 591 M -( string signature of H) s -5 569 M -( The hash H is computed as the HASH hash of the concatenation of the) s -5 558 M -( following:) s -5 536 M -( string V_C, the client's version string \(CR and NL excluded\)) s -5 525 M -( string V_S, the server's version string \(CR and NL excluded\)) s -5 514 M -( string I_C, the payload of the client's SSH_MSG_KEXINIT) s -5 503 M -( string I_S, the payload of the server's SSH_MSG_KEXINIT) s -5 492 M -( string K_S, the host key) s -5 481 M -( mpint e, exchange value sent by the client) s -5 470 M -( mpint f, exchange value sent by the server) s -5 459 M -( mpint K, the shared secret) s -5 437 M -( This value is called the exchange hash, and it is used to) s -5 426 M -( authenticate the key exchange. The exchange hash SHOULD be kept) s -5 415 M -( secret.) s -5 382 M -( The signature algorithm MUST be applied over H, not the original) s -5 371 M -( data. Most signature algorithms include hashing and additional) s -5 360 M -( padding. For example, "ssh-dss" specifies SHA-1 hashing; in that) s -5 349 M -( case, the data is first hashed with HASH to compute H, and H is then) s -5 338 M -( hashed with SHA-1 as part of the signing operation.) s -5 316 M -(7.1 diffie-hellman-group1-sha1) s -5 294 M -( The "diffie-hellman-group1-sha1" method specifies Diffie-Hellman key) s -5 283 M -( exchange with SHA-1 as HASH, and Oakley group 14 [RFC3526] \(2048-bit) s -5 272 M -( MODP Group\). It is included below in hexadecimal and decimal.) s -5 250 M -( The prime p is equal to 2^1024 - 2^960 - 1 + 2^64 * floor\( 2^894 Pi +) s -5 239 M -( 129093 \). Its hexadecimal value is:) s -5 217 M -( FFFFFFFF FFFFFFFF C90FDAA2 2168C234 C4C6628B 80DC1CD1) s -5 206 M -( 29024E08 8A67CC74 020BBEA6 3B139B22 514A0879 8E3404DD) s -5 195 M -( EF9519B3 CD3A431B 302B0A6D F25F1437 4FE1356D 6D51C245) s -5 184 M -( E485B576 625E7EC6 F44C42E9 A637ED6B 0BFF5CB6 F406B7ED) s -5 173 M -( EE386BFB 5A899FA5 AE9F2411 7C4B1FE6 49286651 ECE65381) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 19]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 20 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -( FFFFFFFF FFFFFFFF.) s -5 668 M -( In decimal, this value is:) s -5 646 M -( 179769313486231590770839156793787453197860296048756011706444) s -5 635 M -( 423684197180216158519368947833795864925541502180565485980503) s -5 624 M -( 646440548199239100050792877003355816639229553136239076508735) s -5 613 M -( 759914822574862575007425302077447712589550957937778424442426) s -5 602 M -( 617334727629299387668709205606050270810842907692932019128194) s -5 591 M -( 467627007.) s -5 569 M -( The generator used with this prime is g = 2. The group order q is \(p) s -5 558 M -( - 1\) / 2.) s -5 536 M -(8. Key Re-Exchange) s -5 514 M -( Key re-exchange is started by sending an SSH_MSG_KEXINIT packet when) s -5 503 M -( not already doing a key exchange \(as described in Section Section) s -5 492 M -( 6.1\). When this message is received, a party MUST respond with its) s -5 481 M -( own SSH_MSG_KEXINIT message except when the received SSH_MSG_KEXINIT) s -5 470 M -( already was a reply. Either party MAY initiate the re-exchange, but) s -5 459 M -( roles MUST NOT be changed \(i.e., the server remains the server, and) s -5 448 M -( the client remains the client\).) s -5 415 M -( Key re-exchange is performed using whatever encryption was in effect) s -5 404 M -( when the exchange was started. Encryption, compression, and MAC) s -5 393 M -( methods are not changed before a new SSH_MSG_NEWKEYS is sent after) s -5 382 M -( the key exchange \(as in the initial key exchange\). Re-exchange is) s -5 371 M -( processed identically to the initial key exchange, except for the) s -5 360 M -( session identifier that will remain unchanged. It is permissible to) s -5 349 M -( change some or all of the algorithms during the re-exchange. Host) s -5 338 M -( keys can also change. All keys and initialization vectors are) s -5 327 M -( recomputed after the exchange. Compression and encryption contexts) s -5 316 M -( are reset.) s -5 283 M -( It is recommended that the keys are changed after each gigabyte of) s -5 272 M -( transmitted data or after each hour of connection time, whichever) s -5 261 M -( comes sooner. However, since the re-exchange is a public key) s -5 250 M -( operation, it requires a fair amount of processing power and should) s -5 239 M -( not be performed too often.) s -5 206 M -( More application data may be sent after the SSH_MSG_NEWKEYS packet) s -5 195 M -( has been sent; key exchange does not affect the protocols that lie) s -5 184 M -( above the SSH transport layer.) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 20]) s -_R -S -PStoPSsaved restore -%%Page: (20,21) 11 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 21 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -(9. Service Request) s -5 668 M -( After the key exchange, the client requests a service. The service is) s -5 657 M -( identified by a name. The format of names and procedures for defining) s -5 646 M -( new names are defined in [SSH-ARCH].) s -5 613 M -( Currently, the following names have been reserved:) s -5 591 M -( ssh-userauth) s -5 580 M -( ssh-connection) s -5 558 M -( Similar local naming policy is applied to the service names, as is) s -5 547 M -( applied to the algorithm names; a local service should use the) s -5 536 M -( "servicename@domain" syntax.) s -5 514 M -( byte SSH_MSG_SERVICE_REQUEST) s -5 503 M -( string service name) s -5 481 M -( If the server rejects the service request, it SHOULD send an) s -5 470 M -( appropriate SSH_MSG_DISCONNECT message and MUST disconnect.) s -5 437 M -( When the service starts, it may have access to the session identifier) s -5 426 M -( generated during the key exchange.) s -5 393 M -( If the server supports the service \(and permits the client to use) s -5 382 M -( it\), it MUST respond with the following:) s -5 360 M -( byte SSH_MSG_SERVICE_ACCEPT) s -5 349 M -( string service name) s -5 327 M -( Message numbers used by services should be in the area reserved for) s -5 316 M -( them \(see Section 6 in [SSH-ARCH]\). The transport level will) s -5 305 M -( continue to process its own messages.) s -5 272 M -( Note that after a key exchange with implicit server authentication,) s -5 261 M -( the client MUST wait for response to its service request message) s -5 250 M -( before sending any further data.) s -5 228 M -(10. Additional Messages) s -5 206 M -( Either party may send any of the following messages at any time.) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 21]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 22 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -(10.1 Disconnection Message) s -5 668 M -( byte SSH_MSG_DISCONNECT) s -5 657 M -( uint32 reason code) s -5 646 M -( string description [RFC2279]) s -5 635 M -( string language tag [RFC3066]) s -5 613 M -( This message causes immediate termination of the connection. All) s -5 602 M -( implementations MUST be able to process this message; they SHOULD be) s -5 591 M -( able to send this message.) s -5 569 M -( The sender MUST NOT send or receive any data after this message, and) s -5 558 M -( the recipient MUST NOT accept any data after receiving this message.) s -5 547 M -( The description field gives a more specific explanation in a) s -5 536 M -( human-readable form. The error code gives the reason in a more) s -5 525 M -( machine-readable format \(suitable for localization\), and can have the) s -5 514 M -( following values:) s -5 492 M -( #define SSH_DISCONNECT_HOST_NOT_ALLOWED_TO_CONNECT 1) s -5 481 M -( #define SSH_DISCONNECT_PROTOCOL_ERROR 2) s -5 470 M -( #define SSH_DISCONNECT_KEY_EXCHANGE_FAILED 3) s -5 459 M -( #define SSH_DISCONNECT_RESERVED 4) s -5 448 M -( #define SSH_DISCONNECT_MAC_ERROR 5) s -5 437 M -( #define SSH_DISCONNECT_COMPRESSION_ERROR 6) s -5 426 M -( #define SSH_DISCONNECT_SERVICE_NOT_AVAILABLE 7) s -5 415 M -( #define SSH_DISCONNECT_PROTOCOL_VERSION_NOT_SUPPORTED 8) s -5 404 M -( #define SSH_DISCONNECT_HOST_KEY_NOT_VERIFIABLE 9) s -5 393 M -( #define SSH_DISCONNECT_CONNECTION_LOST 10) s -5 382 M -( #define SSH_DISCONNECT_BY_APPLICATION 11) s -5 371 M -( #define SSH_DISCONNECT_TOO_MANY_CONNECTIONS 12) s -5 360 M -( #define SSH_DISCONNECT_AUTH_CANCELLED_BY_USER 13) s -5 349 M -( #define SSH_DISCONNECT_NO_MORE_AUTH_METHODS_AVAILABLE 14) s -5 338 M -( #define SSH_DISCONNECT_ILLEGAL_USER_NAME 15) s -5 316 M -( If the description string is displayed, control character filtering) s -5 305 M -( discussed in [SSH-ARCH] should be used to avoid attacks by sending) s -5 294 M -( terminal control characters.) s -5 272 M -(10.2 Ignored Data Message) s -5 250 M -( byte SSH_MSG_IGNORE) s -5 239 M -( string data) s -5 217 M -( All implementations MUST understand \(and ignore\) this message at any) s -5 206 M -( time \(after receiving the protocol version\). No implementation is) s -5 195 M -( required to send them. This message can be used as an additional) s -5 184 M -( protection measure against advanced traffic analysis techniques.) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 22]) s -_R -S -PStoPSsaved restore -%%Page: (22,23) 12 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 23 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -(10.3 Debug Message) s -5 668 M -( byte SSH_MSG_DEBUG) s -5 657 M -( boolean always_display) s -5 646 M -( string message [RFC2279]) s -5 635 M -( string language tag [RFC3066]) s -5 613 M -( All implementations MUST understand this message, but they are) s -5 602 M -( allowed to ignore it. This message is used to pass the other side) s -5 591 M -( information that may help debugging. If always_display is TRUE, the) s -5 580 M -( message SHOULD be displayed. Otherwise, it SHOULD NOT be displayed) s -5 569 M -( unless debugging information has been explicitly requested by the) s -5 558 M -( user.) s -5 525 M -( The message doesn't need to contain a newline. It is, however,) s -5 514 M -( allowed to consist of multiple lines separated by CRLF \(Carriage) s -5 503 M -( Return - Line Feed\) pairs.) s -5 470 M -( If the message string is displayed, terminal control character) s -5 459 M -( filtering discussed in [SSH-ARCH] should be used to avoid attacks by) s -5 448 M -( sending terminal control characters.) s -5 426 M -(10.4 Reserved Messages) s -5 404 M -( An implementation MUST respond to all unrecognized messages with an) s -5 393 M -( SSH_MSG_UNIMPLEMENTED message in the order in which the messages were) s -5 382 M -( received. Such messages MUST be otherwise ignored. Later protocol) s -5 371 M -( versions may define other meanings for these message types.) s -5 349 M -( byte SSH_MSG_UNIMPLEMENTED) s -5 338 M -( uint32 packet sequence number of rejected message) s -5 305 M -(11. Summary of Message Numbers) s -5 283 M -( The following message numbers have been defined in this protocol:) s -5 261 M -( #define SSH_MSG_DISCONNECT 1) s -5 250 M -( #define SSH_MSG_IGNORE 2) s -5 239 M -( #define SSH_MSG_UNIMPLEMENTED 3) s -5 228 M -( #define SSH_MSG_DEBUG 4) s -5 217 M -( #define SSH_MSG_SERVICE_REQUEST 5) s -5 206 M -( #define SSH_MSG_SERVICE_ACCEPT 6) s -5 184 M -( #define SSH_MSG_KEXINIT 20) s -5 173 M -( #define SSH_MSG_NEWKEYS 21) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 23]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 24 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -( /* Numbers 30-49 used for kex packets.) s -5 679 M -( Different kex methods may reuse message numbers in) s -5 668 M -( this range. */) s -5 646 M -( #define SSH_MSG_KEXDH_INIT 30) s -5 635 M -( #define SSH_MSG_KEXDH_REPLY 31) s -5 602 M -(12. IANA Considerations) s -5 580 M -( This document is part of a set, the IANA considerations for the SSH) s -5 569 M -( protocol as defined in [SSH-ARCH], [SSH-TRANS], [SSH-USERAUTH],) s -5 558 M -( [SSH-CONNECT] are detailed in [SSH-NUMBERS].) s -5 536 M -(13. Security Considerations) s -5 514 M -( This protocol provides a secure encrypted channel over an insecure) s -5 503 M -( network. It performs server host authentication, key exchange,) s -5 492 M -( encryption, and integrity protection. It also derives a unique) s -5 481 M -( session id that may be used by higher-level protocols.) s -5 459 M -( Full security considerations for this protocol are provided in) s -5 448 M -( Section 8 of [SSH-ARCH]) s -5 426 M -(14. Intellectual Property) s -5 404 M -( The IETF takes no position regarding the validity or scope of any) s -5 393 M -( intellectual property or other rights that might be claimed to) s -5 382 M -( pertain to the implementation or use of the technology described in) s -5 371 M -( this document or the extent to which any license under such rights) s -5 360 M -( might or might not be available; neither does it represent that it) s -5 349 M -( has made any effort to identify any such rights. Information on the) s -5 338 M -( IETF's procedures with respect to rights in standards-track and) s -5 327 M -( standards-related documentation can be found in BCP-11. Copies of) s -5 316 M -( claims of rights made available for publication and any assurances of) s -5 305 M -( licenses to be made available, or the result of an attempt made to) s -5 294 M -( obtain a general license or permission for the use of such) s -5 283 M -( proprietary rights by implementers or users of this specification can) s -5 272 M -( be obtained from the IETF Secretariat.) s -5 250 M -( The IETF has been notified of intellectual property rights claimed in) s -5 239 M -( regard to some or all of the specification contained in this) s -5 228 M -( document. For more information consult the online list of claimed) s -5 217 M -( rights.) s -5 195 M -(15. Additional Information) s -5 173 M -( The current document editor is: [email protected]. Comments on) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 24]) s -_R -S -PStoPSsaved restore -%%Page: (24,25) 13 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 25 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -( this internet draft should be sent to the IETF SECSH working group,) s -5 679 M -( details at: http://ietf.org/html.charters/secsh-charter.html) s -5 657 M -(Normative) s -5 635 M -( [SSH-ARCH]) s -5 624 M -( Ylonen, T., "SSH Protocol Architecture", I-D) s -5 613 M -( draft-ietf-architecture-15.txt, Oct 2003.) s -5 591 M -( [SSH-TRANS]) s -5 580 M -( Ylonen, T., "SSH Transport Layer Protocol", I-D) s -5 569 M -( draft-ietf-transport-17.txt, Oct 2003.) s -5 547 M -( [SSH-USERAUTH]) s -5 536 M -( Ylonen, T., "SSH Authentication Protocol", I-D) s -5 525 M -( draft-ietf-userauth-18.txt, Oct 2003.) s -5 503 M -( [SSH-CONNECT]) s -5 492 M -( Ylonen, T., "SSH Connection Protocol", I-D) s -5 481 M -( draft-ietf-connect-18.txt, Oct 2003.) s -5 459 M -( [SSH-NUMBERS]) s -5 448 M -( Lehtinen, S. and D. Moffat, "SSH Protocol Assigned) s -5 437 M -( Numbers", I-D draft-ietf-secsh-assignednumbers-05.txt, Oct) s -5 426 M -( 2003.) s -5 404 M -( [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate) s -5 393 M -( Requirement Levels", BCP 14, RFC 2119, March 1997.) s -5 371 M -(Informative) s -5 349 M -( [FIPS-186]) s -5 338 M -( Federal Information Processing Standards Publication,) s -5 327 M -( "FIPS PUB 186, Digital Signature Standard", May 1994.) s -5 305 M -( [FIPS-197]) s -5 294 M -( NIST, "FIPS PUB 197 Advanced Encryption Standard \(AES\)",) s -5 283 M -( November 2001.) s -5 261 M -( [FIPS-46-3]) s -5 250 M -( U.S. Dept. of Commerce, "FIPS PUB 46-3, Data Encryption) s -5 239 M -( Standard \(DES\)", October 1999.) s -5 217 M -( [RFC2459] Housley, R., Ford, W., Polk, T. and D. Solo, "Internet) s -5 206 M -( X.509 Public Key Infrastructure Certificate and CRL) s -5 195 M -( Profile", RFC 2459, January 1999.) s -5 173 M -( [RFC1034] Mockapetris, P., "Domain names - concepts and facilities",) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 25]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 26 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -( STD 13, RFC 1034, November 1987.) s -5 668 M -( [RFC3066] Alvestrand, H., "Tags for the Identification of) s -5 657 M -( Languages", BCP 47, RFC 3066, January 2001.) s -5 635 M -( [RFC1950] Deutsch, L. and J-L. Gailly, "ZLIB Compressed Data Format) s -5 624 M -( Specification version 3.3", RFC 1950, May 1996.) s -5 602 M -( [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification) s -5 591 M -( version 1.3", RFC 1951, May 1996.) s -5 569 M -( [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO) s -5 558 M -( 10646", RFC 2279, January 1998.) s -5 536 M -( [RFC2104] Krawczyk, H., Bellare, M. and R. Canetti, "HMAC:) s -5 525 M -( Keyed-Hashing for Message Authentication", RFC 2104,) s -5 514 M -( February 1997.) s -5 492 M -( [RFC2144] Adams, C., "The CAST-128 Encryption Algorithm", RFC 2144,) s -5 481 M -( May 1997.) s -5 459 M -( [RFC2440] Callas, J., Donnerhacke, L., Finney, H. and R. Thayer,) s -5 448 M -( "OpenPGP Message Format", RFC 2440, November 1998.) s -5 426 M -( [RFC2693] Ellison, C., Frantz, B., Lampson, B., Rivest, R., Thomas,) s -5 415 M -( B. and T. Ylonen, "SPKI Certificate Theory", RFC 2693,) s -5 404 M -( September 1999.) s -5 382 M -( [RFC3526] Kivinen, T. and M. Kojo, "More Modular Exponential \(MODP\)) s -5 371 M -( Diffie-Hellman groups for Internet Key Exchange \(IKE\)",) s -5 360 M -( RFC 3526, May 2003.) s -5 338 M -( [SCHNEIER]) s -5 327 M -( Schneier, B., "Applied Cryptography Second Edition:) s -5 316 M -( protocols algorithms and source in code in C", 1996.) s -5 294 M -( [TWOFISH] Schneier, B., "The Twofish Encryptions Algorithm: A) s -5 283 M -( 128-Bit Block Cipher, 1st Edition", March 1999.) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 26]) s -_R -S -PStoPSsaved restore -%%Page: (26,27) 14 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 27 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -(Authors' Addresses) s -5 668 M -( Tatu Ylonen) s -5 657 M -( SSH Communications Security Corp) s -5 646 M -( Fredrikinkatu 42) s -5 635 M -( HELSINKI FIN-00100) s -5 624 M -( Finland) s -5 602 M -( EMail: [email protected]) s -5 569 M -( Darren J. Moffat \(editor\)) s -5 558 M -( Sun Microsystems, Inc) s -5 547 M -( 17 Network Circle) s -5 536 M -( Menlo Park 95025) s -5 525 M -( USA) s -5 503 M -( EMail: [email protected]) s -5 481 M -(Appendix A. Contibutors) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 27]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 28 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -(Intellectual Property Statement) s -5 668 M -( The IETF takes no position regarding the validity or scope of any) s -5 657 M -( intellectual property or other rights that might be claimed to) s -5 646 M -( pertain to the implementation or use of the technology described in) s -5 635 M -( this document or the extent to which any license under such rights) s -5 624 M -( might or might not be available; neither does it represent that it) s -5 613 M -( has made any effort to identify any such rights. Information on the) s -5 602 M -( IETF's procedures with respect to rights in standards-track and) s -5 591 M -( standards-related documentation can be found in BCP-11. Copies of) s -5 580 M -( claims of rights made available for publication and any assurances of) s -5 569 M -( licenses to be made available, or the result of an attempt made to) s -5 558 M -( obtain a general license or permission for the use of such) s -5 547 M -( proprietary rights by implementors or users of this specification can) s -5 536 M -( be obtained from the IETF Secretariat.) s -5 514 M -( The IETF invites any interested party to bring to its attention any) s -5 503 M -( copyrights, patents or patent applications, or other proprietary) s -5 492 M -( rights which may cover technology that may be required to practice) s -5 481 M -( this standard. Please address the information to the IETF Executive) s -5 470 M -( Director.) s -5 448 M -( The IETF has been notified of intellectual property rights claimed in) s -5 437 M -( regard to some or all of the specification contained in this) s -5 426 M -( document. For more information consult the online list of claimed) s -5 415 M -( rights.) s -5 382 M -(Full Copyright Statement) s -5 360 M -( Copyright \(C\) The Internet Society \(2003\). All Rights Reserved.) s -5 338 M -( This document and translations of it may be copied and furnished to) s -5 327 M -( others, and derivative works that comment on or otherwise explain it) s -5 316 M -( or assist in its implementation may be prepared, copied, published) s -5 305 M -( and distributed, in whole or in part, without restriction of any) s -5 294 M -( kind, provided that the above copyright notice and this paragraph are) s -5 283 M -( included on all such copies and derivative works. However, this) s -5 272 M -( document itself may not be modified in any way, such as by removing) s -5 261 M -( the copyright notice or references to the Internet Society or other) s -5 250 M -( Internet organizations, except as needed for the purpose of) s -5 239 M -( developing Internet standards in which case the procedures for) s -5 228 M -( copyrights defined in the Internet Standards process must be) s -5 217 M -( followed, or as required to translate it into languages other than) s -5 206 M -( English.) s -5 184 M -( The limited permissions granted above are perpetual and will not be) s -5 173 M -( revoked by the Internet Society or its successors or assignees.) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 28]) s -_R -S -PStoPSsaved restore -%%Page: (28,29) 15 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 29 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Transport Layer Protocol Oct 2003) s -5 690 M -( This document and the information contained herein is provided on an) s -5 679 M -( "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING) s -5 668 M -( TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING) s -5 657 M -( BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION) s -5 646 M -( HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF) s -5 635 M -( MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.) s -5 602 M -(Acknowledgment) s -5 580 M -( Funding for the RFC Editor function is currently provided by the) s -5 569 M -( Internet Society.) s -5 129 M -(Ylonen & Moffat, Editor Expires March 31, 2004 [Page 29]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -showpage -PStoPSsaved restore -%%Trailer -%%Pages: 29 -%%DocumentNeededResources: font Courier-Bold Courier -%%EOF diff --git a/lib/ssh/doc/standard/draft-ietf-secsh-transport-17.txt b/lib/ssh/doc/standard/draft-ietf-secsh-transport-17.txt deleted file mode 100644 index 9073ea52b2..0000000000 --- a/lib/ssh/doc/standard/draft-ietf-secsh-transport-17.txt +++ /dev/null @@ -1,1624 +0,0 @@ - - - -Network Working Group T. Ylonen -Internet-Draft SSH Communications Security Corp -Expires: March 31, 2004 D. Moffat, Editor, Ed. - Sun Microsystems, Inc - Oct 2003 - - - SSH Transport Layer Protocol - draft-ietf-secsh-transport-17.txt - -Status of this Memo - - This document is an Internet-Draft and is in full conformance with - all provisions of Section 10 of RFC2026. - - Internet-Drafts are working documents of the Internet Engineering - Task Force (IETF), its areas, and its working groups. Note that other - groups may also distribute working documents as Internet-Drafts. - - Internet-Drafts are draft documents valid for a maximum of six months - and may be updated, replaced, or obsoleted by other documents at any - time. It is inappropriate to use Internet-Drafts as reference - material or to cite them other than as "work in progress." - - The list of current Internet-Drafts can be accessed at http:// - www.ietf.org/ietf/1id-abstracts.txt. - - The list of Internet-Draft Shadow Directories can be accessed at - http://www.ietf.org/shadow.html. - - This Internet-Draft will expire on March 31, 2004. - -Copyright Notice - - Copyright (C) The Internet Society (2003). All Rights Reserved. - -Abstract - - SSH is a protocol for secure remote login and other secure network - services over an insecure network. - - This document describes the SSH transport layer protocol which - typically runs on top of TCP/IP. The protocol can be used as a basis - for a number of secure network services. It provides strong - encryption, server authentication, and integrity protection. It may - also provide compression. - - Key exchange method, public key algorithm, symmetric encryption - algorithm, message authentication algorithm, and hash algorithm are - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 1] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - - all negotiated. - - This document also describes the Diffie-Hellman key exchange method - and the minimal set of algorithms that are needed to implement the - SSH transport layer protocol. - -Table of Contents - - 1. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 3 - 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 - 3. Conventions Used in This Document . . . . . . . . . . . . . 3 - 4. Connection Setup . . . . . . . . . . . . . . . . . . . . . . 3 - 4.1 Use over TCP/IP . . . . . . . . . . . . . . . . . . . . . . 4 - 4.2 Protocol Version Exchange . . . . . . . . . . . . . . . . . 4 - 4.3 Compatibility With Old SSH Versions . . . . . . . . . . . . 4 - 4.3.1 Old Client, New Server . . . . . . . . . . . . . . . . . . . 5 - 4.3.2 New Client, Old Server . . . . . . . . . . . . . . . . . . . 5 - 5. Binary Packet Protocol . . . . . . . . . . . . . . . . . . . 5 - 5.1 Maximum Packet Length . . . . . . . . . . . . . . . . . . . 6 - 5.2 Compression . . . . . . . . . . . . . . . . . . . . . . . . 7 - 5.3 Encryption . . . . . . . . . . . . . . . . . . . . . . . . . 7 - 5.4 Data Integrity . . . . . . . . . . . . . . . . . . . . . . . 9 - 5.5 Key Exchange Methods . . . . . . . . . . . . . . . . . . . . 10 - 5.6 Public Key Algorithms . . . . . . . . . . . . . . . . . . . 11 - 6. Key Exchange . . . . . . . . . . . . . . . . . . . . . . . . 13 - 6.1 Algorithm Negotiation . . . . . . . . . . . . . . . . . . . 13 - 6.2 Output from Key Exchange . . . . . . . . . . . . . . . . . . 16 - 6.3 Taking Keys Into Use . . . . . . . . . . . . . . . . . . . . 17 - 7. Diffie-Hellman Key Exchange . . . . . . . . . . . . . . . . 18 - 7.1 diffie-hellman-group1-sha1 . . . . . . . . . . . . . . . . . 19 - 8. Key Re-Exchange . . . . . . . . . . . . . . . . . . . . . . 20 - 9. Service Request . . . . . . . . . . . . . . . . . . . . . . 21 - 10. Additional Messages . . . . . . . . . . . . . . . . . . . . 21 - 10.1 Disconnection Message . . . . . . . . . . . . . . . . . . . 22 - 10.2 Ignored Data Message . . . . . . . . . . . . . . . . . . . . 22 - 10.3 Debug Message . . . . . . . . . . . . . . . . . . . . . . . 23 - 10.4 Reserved Messages . . . . . . . . . . . . . . . . . . . . . 23 - 11. Summary of Message Numbers . . . . . . . . . . . . . . . . . 23 - 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . 24 - 13. Security Considerations . . . . . . . . . . . . . . . . . . 24 - 14. Intellectual Property . . . . . . . . . . . . . . . . . . . 24 - 15. Additional Information . . . . . . . . . . . . . . . . . . . 24 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 26 - Normative . . . . . . . . . . . . . . . . . . . . . . . . . 25 - Informative . . . . . . . . . . . . . . . . . . . . . . . . 25 - A. Contibutors . . . . . . . . . . . . . . . . . . . . . . . . 27 - Intellectual Property and Copyright Statements . . . . . . . 28 - - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 2] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - -1. Contributors - - The major original contributors of this document were: Tatu Ylonen, - Tero Kivinen, Timo J. Rinne, Sami Lehtinen (all of SSH Communications - Security Corp), and Markku-Juhani O. Saarinen (University of - Jyvaskyla) - - The document editor is: [email protected]. Comments on this - internet draft should be sent to the IETF SECSH working group, - details at: http://ietf.org/html.charters/secsh-charter.html - -2. Introduction - - The SSH transport layer is a secure low level transport protocol. It - provides strong encryption, cryptographic host authentication, and - integrity protection. - - Authentication in this protocol level is host-based; this protocol - does not perform user authentication. A higher level protocol for - user authentication can be designed on top of this protocol. - - The protocol has been designed to be simple, flexible, to allow - parameter negotiation, and to minimize the number of round-trips. - Key exchange method, public key algorithm, symmetric encryption - algorithm, message authentication algorithm, and hash algorithm are - all negotiated. It is expected that in most environments, only 2 - round-trips will be needed for full key exchange, server - authentication, service request, and acceptance notification of - service request. The worst case is 3 round-trips. - -3. Conventions Used in This Document - - The keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", - and "MAY" that appear in this document are to be interpreted as - described in [RFC2119]. - - The used data types and terminology are specified in the architecture - document [SSH-ARCH]. - - The architecture document also discusses the algorithm naming - conventions that MUST be used with the SSH protocols. - -4. Connection Setup - - SSH works over any 8-bit clean, binary-transparent transport. The - underlying transport SHOULD protect against transmission errors as - such errors cause the SSH connection to terminate. - - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 3] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - - The client initiates the connection. - -4.1 Use over TCP/IP - - When used over TCP/IP, the server normally listens for connections on - port 22. This port number has been registered with the IANA, and has - been officially assigned for SSH. - -4.2 Protocol Version Exchange - - When the connection has been established, both sides MUST send an - identification string of the form "SSH-protoversion-softwareversion - comments", followed by carriage return and newline characters (ASCII - 13 and 10, respectively). Both sides MUST be able to process - identification strings without carriage return character. No null - character is sent. The maximum length of the string is 255 - characters, including the carriage return and newline. - - The part of the identification string preceding carriage return and - newline is used in the Diffie-Hellman key exchange (see Section - Section 7). - - The server MAY send other lines of data before sending the version - string. Each line SHOULD be terminated by a carriage return and - newline. Such lines MUST NOT begin with "SSH-", and SHOULD be - encoded in ISO-10646 UTF-8 [RFC2279] (language is not specified). - Clients MUST be able to process such lines; they MAY be silently - ignored, or MAY be displayed to the client user; if they are - displayed, control character filtering discussed in [SSH-ARCH] SHOULD - be used. The primary use of this feature is to allow TCP-wrappers to - display an error message before disconnecting. - - Version strings MUST consist of printable US-ASCII characters, not - including whitespaces or a minus sign (-). The version string is - primarily used to trigger compatibility extensions and to indicate - the capabilities of an implementation. The comment string should - contain additional information that might be useful in solving user - problems. - - The protocol version described in this document is 2.0. - - Key exchange will begin immediately after sending this identifier. - All packets following the identification string SHALL use the binary - packet protocol, to be described below. - -4.3 Compatibility With Old SSH Versions - - During the transition period, it is important to be able to work in a - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 4] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - - way that is compatible with the installed SSH clients and servers - that use an older version of the protocol. Information in this - section is only relevant for implementations supporting compatibility - with SSH versions 1.x. There is no standards track or informational - draft available that defines the SSH 1.x protocol. The only known - documentation of the 1.x protocol is contained in README files that - are shipped along with the source code. - -4.3.1 Old Client, New Server - - Server implementations MAY support a configurable "compatibility" - flag that enables compatibility with old versions. When this flag is - on, the server SHOULD identify its protocol version as "1.99". - Clients using protocol 2.0 MUST be able to identify this as identical - to "2.0". In this mode the server SHOULD NOT send the carriage - return character (ASCII 13) after the version identification string. - - In the compatibility mode the server SHOULD NOT send any further data - after its initialization string until it has received an - identification string from the client. The server can then determine - whether the client is using an old protocol, and can revert to the - old protocol if required. In the compatibility mode, the server MUST - NOT send additional data before the version string. - - When compatibility with old clients is not needed, the server MAY - send its initial key exchange data immediately after the - identification string. - -4.3.2 New Client, Old Server - - Since the new client MAY immediately send additional data after its - identification string (before receiving server's identification), the - old protocol may already have been corrupted when the client learns - that the server is old. When this happens, the client SHOULD close - the connection to the server, and reconnect using the old protocol. - -5. Binary Packet Protocol - - Each packet is in the following format: - - uint32 packet_length - byte padding_length - byte[n1] payload; n1 = packet_length - padding_length - 1 - byte[n2] random padding; n2 = padding_length - byte[m] mac (message authentication code); m = mac_length - - packet_length - - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 5] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - - The length of the packet (bytes), not including MAC or the - packet_length field itself. - - padding_length - Length of padding (bytes). - - payload - The useful contents of the packet. If compression has been - negotiated, this field is compressed. Initially, compression - MUST be "none". - - random padding - Arbitrary-length padding, such that the total length of - (packet_length || padding_length || payload || padding) is a - multiple of the cipher block size or 8, whichever is larger. - There MUST be at least four bytes of padding. The padding - SHOULD consist of random bytes. The maximum amount of padding - is 255 bytes. - - mac - Message authentication code. If message authentication has - been negotiated, this field contains the MAC bytes. Initially, - the MAC algorithm MUST be "none". - - - Note that length of the concatenation of packet length, padding - length, payload, and padding MUST be a multiple of the cipher block - size or 8, whichever is larger. This constraint MUST be enforced - even when using stream ciphers. Note that the packet length field is - also encrypted, and processing it requires special care when sending - or receiving packets. - - The minimum size of a packet is 16 (or the cipher block size, - whichever is larger) bytes (plus MAC); implementations SHOULD decrypt - the length after receiving the first 8 (or cipher block size, - whichever is larger) bytes of a packet. - -5.1 Maximum Packet Length - - All implementations MUST be able to process packets with uncompressed - payload length of 32768 bytes or less and total packet size of 35000 - bytes or less (including length, padding length, payload, padding, - and MAC.). The maximum of 35000 bytes is an arbitrary chosen value - larger than uncompressed size. Implementations SHOULD support longer - packets, where they might be needed, e.g. if an implementation wants - to send a very large number of certificates. Such packets MAY be - sent if the version string indicates that the other party is able to - process them. However, implementations SHOULD check that the packet - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 6] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - - length is reasonable for the implementation to avoid - denial-of-service and/or buffer overflow attacks. - -5.2 Compression - - If compression has been negotiated, the payload field (and only it) - will be compressed using the negotiated algorithm. The length field - and MAC will be computed from the compressed payload. Encryption will - be done after compression. - - Compression MAY be stateful, depending on the method. Compression - MUST be independent for each direction, and implementations MUST - allow independently choosing the algorithm for each direction. - - The following compression methods are currently defined: - - none REQUIRED no compression - zlib OPTIONAL ZLIB (LZ77) compression - - The "zlib" compression is described in [RFC1950] and in [RFC1951]. - The compression context is initialized after each key exchange, and - is passed from one packet to the next with only a partial flush being - performed at the end of each packet. A partial flush means that the - current compressed block is ended and all data will be output. If the - current block is not a stored block, one or more empty blocks are - added after the current block to ensure that there are at least 8 - bits counting from the start of the end-of-block code of the current - block to the end of the packet payload. - - Additional methods may be defined as specified in [SSH-ARCH]. - -5.3 Encryption - - An encryption algorithm and a key will be negotiated during the key - exchange. When encryption is in effect, the packet length, padding - length, payload and padding fields of each packet MUST be encrypted - with the given algorithm. - - The encrypted data in all packets sent in one direction SHOULD be - considered a single data stream. For example, initialization vectors - SHOULD be passed from the end of one packet to the beginning of the - next packet. All ciphers SHOULD use keys with an effective key length - of 128 bits or more. - - The ciphers in each direction MUST run independently of each other, - and implementations MUST allow independently choosing the algorithm - for each direction (if multiple algorithms are allowed by local - policy). - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 7] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - - The following ciphers are currently defined: - - 3des-cbc REQUIRED three-key 3DES in CBC mode - blowfish-cbc OPTIONALi Blowfish in CBC mode - twofish256-cbc OPTIONAL Twofish in CBC mode, - with 256-bit key - twofish-cbc OPTIONAL alias for "twofish256-cbc" (this - is being retained for - historical reasons) - twofish192-cbc OPTIONAL Twofish with 192-bit key - twofish128-cbc OPTIONAL Twofish with 128-bit key - aes256-cbc OPTIONAL AES (Rijndael) in CBC mode, - with 256-bit key - aes192-cbc OPTIONAL AES with 192-bit key - aes128-cbc RECOMMENDED AES with 128-bit key - serpent256-cbc OPTIONAL Serpent in CBC mode, with - 256-bit key - serpent192-cbc OPTIONAL Serpent with 192-bit key - serpent128-cbc OPTIONAL Serpent with 128-bit key - arcfour OPTIONAL the ARCFOUR stream cipher - idea-cbc OPTIONAL IDEA in CBC mode - cast128-cbc OPTIONAL CAST-128 in CBC mode - none OPTIONAL no encryption; NOT RECOMMENDED - - The "3des-cbc" cipher is three-key triple-DES - (encrypt-decrypt-encrypt), where the first 8 bytes of the key are - used for the first encryption, the next 8 bytes for the decryption, - and the following 8 bytes for the final encryption. This requires 24 - bytes of key data (of which 168 bits are actually used). To - implement CBC mode, outer chaining MUST be used (i.e., there is only - one initialization vector). This is a block cipher with 8 byte - blocks. This algorithm is defined in [FIPS-46-3] - - The "blowfish-cbc" cipher is Blowfish in CBC mode, with 128 bit keys - [SCHNEIER]. This is a block cipher with 8 byte blocks. - - The "twofish-cbc" or "twofish256-cbc" cipher is Twofish in CBC mode, - with 256 bit keys as described [TWOFISH]. This is a block cipher with - 16 byte blocks. - - The "twofish192-cbc" cipher. Same as above but with 192-bit key. - - The "twofish128-cbc" cipher. Same as above but with 128-bit key. - - The "aes256-cbc" cipher is AES (Advanced Encryption Standard) - [FIPS-197], formerly Rijndael, in CBC mode. This version uses 256-bit - key. - - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 8] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - - The "aes192-cbc" cipher. Same as above but with 192-bit key. - - The "aes128-cbc" cipher. Same as above but with 128-bit key. - - The "serpent256-cbc" cipher in CBC mode, with 256-bit key as - described in the Serpent AES submission. - - The "serpent192-cbc" cipher. Same as above but with 192-bit key. - - The "serpent128-cbc" cipher. Same as above but with 128-bit key. - - The "arcfour" is the Arcfour stream cipher with 128 bit keys. The - Arcfour cipher is believed to be compatible with the RC4 cipher - [SCHNEIER]. RC4 is a registered trademark of RSA Data Security Inc. - Arcfour (and RC4) has problems with weak keys, and should be used - with caution. - - The "idea-cbc" cipher is the IDEA cipher in CBC mode [SCHNEIER]. - - The "cast128-cbc" cipher is the CAST-128 cipher in CBC mode - [RFC2144]. - - The "none" algorithm specifies that no encryption is to be done. - Note that this method provides no confidentiality protection, and it - is not recommended. Some functionality (e.g. password - authentication) may be disabled for security reasons if this cipher - is chosen. - - Additional methods may be defined as specified in [SSH-ARCH]. - -5.4 Data Integrity - - Data integrity is protected by including with each packet a message - authentication code (MAC) that is computed from a shared secret, - packet sequence number, and the contents of the packet. - - The message authentication algorithm and key are negotiated during - key exchange. Initially, no MAC will be in effect, and its length - MUST be zero. After key exchange, the selected MAC will be computed - before encryption from the concatenation of packet data: - - mac = MAC(key, sequence_number || unencrypted_packet) - - where unencrypted_packet is the entire packet without MAC (the length - fields, payload and padding), and sequence_number is an implicit - packet sequence number represented as uint32. The sequence number is - initialized to zero for the first packet, and is incremented after - every packet (regardless of whether encryption or MAC is in use). It - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 9] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - - is never reset, even if keys/algorithms are renegotiated later. It - wraps around to zero after every 2^32 packets. The packet sequence - number itself is not included in the packet sent over the wire. - - The MAC algorithms for each direction MUST run independently, and - implementations MUST allow choosing the algorithm independently for - both directions. - - The MAC bytes resulting from the MAC algorithm MUST be transmitted - without encryption as the last part of the packet. The number of MAC - bytes depends on the algorithm chosen. - - The following MAC algorithms are currently defined: - - hmac-sha1 REQUIRED HMAC-SHA1 (digest length = key - length = 20) - hmac-sha1-96 RECOMMENDED first 96 bits of HMAC-SHA1 (digest - length = 12, key length = 20) - hmac-md5 OPTIONAL HMAC-MD5 (digest length = key - length = 16) - hmac-md5-96 OPTIONAL first 96 bits of HMAC-MD5 (digest - length = 12, key length = 16) - none OPTIONAL no MAC; NOT RECOMMENDED - - Figure 1 - - The "hmac-*" algorithms are described in [RFC2104] The "*-n" MACs use - only the first n bits of the resulting value. - - The hash algorithms are described in [SCHNEIER]. - - Additional methods may be defined as specified in [SSH-ARCH]. - -5.5 Key Exchange Methods - - The key exchange method specifies how one-time session keys are - generated for encryption and for authentication, and how the server - authentication is done. - - Only one REQUIRED key exchange method has been defined: - - diffie-hellman-group1-sha1 REQUIRED - - This method is described later in this document. - - Additional methods may be defined as specified in [SSH-ARCH]. - - - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 10] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - -5.6 Public Key Algorithms - - This protocol has been designed to be able to operate with almost any - public key format, encoding, and algorithm (signature and/or - encryption). - - There are several aspects that define a public key type: - o Key format: how is the key encoded and how are certificates - represented. The key blobs in this protocol MAY contain - certificates in addition to keys. - o Signature and/or encryption algorithms. Some key types may not - support both signing and encryption. Key usage may also be - restricted by policy statements in e.g. certificates. In this - case, different key types SHOULD be defined for the different - policy alternatives. - o Encoding of signatures and/or encrypted data. This includes but is - not limited to padding, byte order, and data formats. - - The following public key and/or certificate formats are currently defined: - - ssh-dss REQUIRED sign Raw DSS Key - ssh-rsa RECOMMENDED sign Raw RSA Key - x509v3-sign-rsa OPTIONAL sign X.509 certificates (RSA key) - x509v3-sign-dss OPTIONAL sign X.509 certificates (DSS key) - spki-sign-rsa OPTIONAL sign SPKI certificates (RSA key) - spki-sign-dss OPTIONAL sign SPKI certificates (DSS key) - pgp-sign-rsa OPTIONAL sign OpenPGP certificates (RSA key) - pgp-sign-dss OPTIONAL sign OpenPGP certificates (DSS key) - - Additional key types may be defined as specified in [SSH-ARCH]. - - The key type MUST always be explicitly known (from algorithm - negotiation or some other source). It is not normally included in - the key blob. - - Certificates and public keys are encoded as follows: - - string certificate or public key format identifier - byte[n] key/certificate data - - The certificate part may have be a zero length string, but a public - key is required. This is the public key that will be used for - authentication; the certificate sequence contained in the certificate - blob can be used to provide authorization. - - Public key / certifcate formats that do not explicitly specify a - signature format identifier MUST use the public key / certificate - format identifier as the signature identifier. - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 11] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - - Signatures are encoded as follows: - string signature format identifier (as specified by the - public key / cert format) - byte[n] signature blob in format specific encoding. - - - The "ssh-dss" key format has the following specific encoding: - - string "ssh-dss" - mpint p - mpint q - mpint g - mpint y - - Here the p, q, g, and y parameters form the signature key blob. - - Signing and verifying using this key format is done according to the - Digital Signature Standard [FIPS-186] using the SHA-1 hash. A - description can also be found in [SCHNEIER]. - - The resulting signature is encoded as follows: - - string "ssh-dss" - string dss_signature_blob - - dss_signature_blob is encoded as a string containing r followed by s - (which are 160 bits long integers, without lengths or padding, - unsigned and in network byte order). - - The "ssh-rsa" key format has the following specific encoding: - - string "ssh-rsa" - mpint e - mpint n - - Here the e and n parameters form the signature key blob. - - Signing and verifying using this key format is done according to - [SCHNEIER] and [PKCS1] using the SHA-1 hash. - - The resulting signature is encoded as follows: - - string "ssh-rsa" - string rsa_signature_blob - - rsa_signature_blob is encoded as a string containing s (which is an - integer, without lengths or padding, unsigned and in network byte - order). - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 12] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - - The "spki-sign-rsa" method indicates that the certificate blob - contains a sequence of SPKI certificates. The format of SPKI - certificates is described in [RFC2693]. This method indicates that - the key (or one of the keys in the certificate) is an RSA-key. - - The "spki-sign-dss". As above, but indicates that the key (or one of - the keys in the certificate) is a DSS-key. - - The "pgp-sign-rsa" method indicates the certificates, the public key, - and the signature are in OpenPGP compatible binary format - ([RFC2440]). This method indicates that the key is an RSA-key. - - The "pgp-sign-dss". As above, but indicates that the key is a - DSS-key. - -6. Key Exchange - - Key exchange begins by each side sending lists of supported - algorithms. Each side has a preferred algorithm in each category, and - it is assumed that most implementations at any given time will use - the same preferred algorithm. Each side MAY guess which algorithm - the other side is using, and MAY send an initial key exchange packet - according to the algorithm if appropriate for the preferred method. - - Guess is considered wrong, if: - o the kex algorithm and/or the host key algorithm is guessed wrong - (server and client have different preferred algorithm), or - o if any of the other algorithms cannot be agreed upon (the - procedure is defined below in Section Section 6.1). - - Otherwise, the guess is considered to be right and the optimistically - sent packet MUST be handled as the first key exchange packet. - - However, if the guess was wrong, and a packet was optimistically sent - by one or both parties, such packets MUST be ignored (even if the - error in the guess would not affect the contents of the initial - packet(s)), and the appropriate side MUST send the correct initial - packet. - - Server authentication in the key exchange MAY be implicit. After a - key exchange with implicit server authentication, the client MUST - wait for response to its service request message before sending any - further data. - -6.1 Algorithm Negotiation - - Key exchange begins by each side sending the following packet: - - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 13] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - - byte SSH_MSG_KEXINIT - byte[16] cookie (random bytes) - string kex_algorithms - string server_host_key_algorithms - string encryption_algorithms_client_to_server - string encryption_algorithms_server_to_client - string mac_algorithms_client_to_server - string mac_algorithms_server_to_client - string compression_algorithms_client_to_server - string compression_algorithms_server_to_client - string languages_client_to_server - string languages_server_to_client - boolean first_kex_packet_follows - uint32 0 (reserved for future extension) - - Each of the algorithm strings MUST be a comma-separated list of - algorithm names (see ''Algorithm Naming'' in [SSH-ARCH]). Each - supported (allowed) algorithm MUST be listed in order of preference. - - The first algorithm in each list MUST be the preferred (guessed) - algorithm. Each string MUST contain at least one algorithm name. - - - cookie - The cookie MUST be a random value generated by the sender. Its - purpose is to make it impossible for either side to fully - determine the keys and the session identifier. - - kex_algorithms - Key exchange algorithms were defined above. The first - algorithm MUST be the preferred (and guessed) algorithm. If - both sides make the same guess, that algorithm MUST be used. - Otherwise, the following algorithm MUST be used to choose a key - exchange method: iterate over client's kex algorithms, one at a - time. Choose the first algorithm that satisfies the following - conditions: - + the server also supports the algorithm, - + if the algorithm requires an encryption-capable host key, - there is an encryption-capable algorithm on the server's - server_host_key_algorithms that is also supported by the - client, and - + if the algorithm requires a signature-capable host key, - there is a signature-capable algorithm on the server's - server_host_key_algorithms that is also supported by the - client. - + If no algorithm satisfying all these conditions can be - found, the connection fails, and both sides MUST disconnect. - - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 14] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - - server_host_key_algorithms - List of the algorithms supported for the server host key. The - server lists the algorithms for which it has host keys; the - client lists the algorithms that it is willing to accept. - (There MAY be multiple host keys for a host, possibly with - different algorithms.) - - Some host keys may not support both signatures and encryption - (this can be determined from the algorithm), and thus not all - host keys are valid for all key exchange methods. - - Algorithm selection depends on whether the chosen key exchange - algorithm requires a signature or encryption capable host key. - It MUST be possible to determine this from the public key - algorithm name. The first algorithm on the client's list that - satisfies the requirements and is also supported by the server - MUST be chosen. If there is no such algorithm, both sides MUST - disconnect. - - encryption_algorithms - Lists the acceptable symmetric encryption algorithms in order - of preference. The chosen encryption algorithm to each - direction MUST be the first algorithm on the client's list - that is also on the server's list. If there is no such - algorithm, both sides MUST disconnect. - - Note that "none" must be explicitly listed if it is to be - acceptable. The defined algorithm names are listed in Section - Section 5.3. - - mac_algorithms - Lists the acceptable MAC algorithms in order of preference. - The chosen MAC algorithm MUST be the first algorithm on the - client's list that is also on the server's list. If there is - no such algorithm, both sides MUST disconnect. - - Note that "none" must be explicitly listed if it is to be - acceptable. The MAC algorithm names are listed in Section - Figure 1. - - compression_algorithms - Lists the acceptable compression algorithms in order of - preference. The chosen compression algorithm MUST be the first - algorithm on the client's list that is also on the server's - list. If there is no such algorithm, both sides MUST - disconnect. - - - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 15] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - - Note that "none" must be explicitly listed if it is to be - acceptable. The compression algorithm names are listed in - Section Section 5.2. - - languages - This is a comma-separated list of language tags in order of - preference [RFC3066]. Both parties MAY ignore this list. If - there are no language preferences, this list SHOULD be empty. - Language tags SHOULD NOT be present unless they are known to be - needed by the sending party. - - first_kex_packet_follows - Indicates whether a guessed key exchange packet follows. If a - guessed packet will be sent, this MUST be TRUE. If no guessed - packet will be sent, this MUST be FALSE. - - After receiving the SSH_MSG_KEXINIT packet from the other side, - each party will know whether their guess was right. If the - other party's guess was wrong, and this field was TRUE, the - next packet MUST be silently ignored, and both sides MUST then - act as determined by the negotiated key exchange method. If - the guess was right, key exchange MUST continue using the - guessed packet. - - After the KEXINIT packet exchange, the key exchange algorithm is run. - It may involve several packet exchanges, as specified by the key - exchange method. - -6.2 Output from Key Exchange - - The key exchange produces two values: a shared secret K, and an - exchange hash H. Encryption and authentication keys are derived from - these. The exchange hash H from the first key exchange is - additionally used as the session identifier, which is a unique - identifier for this connection. It is used by authentication methods - as a part of the data that is signed as a proof of possession of a - private key. Once computed, the session identifier is not changed, - even if keys are later re-exchanged. - - - Each key exchange method specifies a hash function that is used in - the key exchange. The same hash algorithm MUST be used in key - derivation. Here, we'll call it HASH. - - - Encryption keys MUST be computed as HASH of a known value and K as - follows: - - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 16] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - - o Initial IV client to server: HASH(K || H || "A" || session_id) - (Here K is encoded as mpint and "A" as byte and session_id as raw - data."A" means the single character A, ASCII 65). - o Initial IV server to client: HASH(K || H || "B" || session_id) - o Encryption key client to server: HASH(K || H || "C" || session_id) - o Encryption key server to client: HASH(K || H || "D" || session_id) - o Integrity key client to server: HASH(K || H || "E" || session_id) - o Integrity key server to client: HASH(K || H || "F" || session_id) - - Key data MUST be taken from the beginning of the hash output. 128 - bits (16 bytes) MUST be used for algorithms with variable-length - keys. The only variable key length algorithm defined in this document - is arcfour). For other algorithms, as many bytes as are needed are - taken from the beginning of the hash value. If the key length needed - is longer than the output of the HASH, the key is extended by - computing HASH of the concatenation of K and H and the entire key so - far, and appending the resulting bytes (as many as HASH generates) to - the key. This process is repeated until enough key material is - available; the key is taken from the beginning of this value. In - other words: - - K1 = HASH(K || H || X || session_id) (X is e.g. "A") - K2 = HASH(K || H || K1) - K3 = HASH(K || H || K1 || K2) - ... - key = K1 || K2 || K3 || ... - - This process will lose entropy if the amount of entropy in K is - larger than the internal state size of HASH. - -6.3 Taking Keys Into Use - - Key exchange ends by each side sending an SSH_MSG_NEWKEYS message. - This message is sent with the old keys and algorithms. All messages - sent after this message MUST use the new keys and algorithms. - - - When this message is received, the new keys and algorithms MUST be - taken into use for receiving. - - - This message is the only valid message after key exchange, in - addition to SSH_MSG_DEBUG, SSH_MSG_DISCONNECT and SSH_MSG_IGNORE - messages. The purpose of this message is to ensure that a party is - able to respond with a disconnect message that the other party can - understand if something goes wrong with the key exchange. - Implementations MUST NOT accept any other messages after key exchange - before receiving SSH_MSG_NEWKEYS. - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 17] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - - byte SSH_MSG_NEWKEYS - - -7. Diffie-Hellman Key Exchange - - The Diffie-Hellman key exchange provides a shared secret that can not - be determined by either party alone. The key exchange is combined - with a signature with the host key to provide host authentication. - - - In the following description (C is the client, S is the server; p is - a large safe prime, g is a generator for a subgroup of GF(p), and q - is the order of the subgroup; V_S is S's version string; V_C is C's - version string; K_S is S's public host key; I_C is C's KEXINIT - message and I_S S's KEXINIT message which have been exchanged before - this part begins): - - - 1. C generates a random number x (1 < x < q) and computes e = g^x - mod p. C sends "e" to S. - - 2. S generates a random number y (0 < y < q) and computes f = g^y - mod p. S receives "e". It computes K = e^y mod p, H = hash(V_C - || V_S || I_C || I_S || K_S || e || f || K) (these elements are - encoded according to their types; see below), and signature s on - H with its private host key. S sends "K_S || f || s" to C. The - signing operation may involve a second hashing operation. - - 3. C verifies that K_S really is the host key for S (e.g. using - certificates or a local database). C is also allowed to accept - the key without verification; however, doing so will render the - protocol insecure against active attacks (but may be desirable - for practical reasons in the short term in many environments). C - then computes K = f^x mod p, H = hash(V_C || V_S || I_C || I_S || - K_S || e || f || K), and verifies the signature s on H. - - Either side MUST NOT send or accept e or f values that are not in the - range [1, p-1]. If this condition is violated, the key exchange - fails. - - - This is implemented with the following messages. The hash algorithm - for computing the exchange hash is defined by the method name, and is - called HASH. The public key algorithm for signing is negotiated with - the KEXINIT messages. - - First, the client sends the following: - - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 18] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - - byte SSH_MSG_KEXDH_INIT - mpint e - - - The server responds with the following: - - byte SSH_MSG_KEXDH_REPLY - string server public host key and certificates (K_S) - mpint f - string signature of H - - The hash H is computed as the HASH hash of the concatenation of the - following: - - string V_C, the client's version string (CR and NL excluded) - string V_S, the server's version string (CR and NL excluded) - string I_C, the payload of the client's SSH_MSG_KEXINIT - string I_S, the payload of the server's SSH_MSG_KEXINIT - string K_S, the host key - mpint e, exchange value sent by the client - mpint f, exchange value sent by the server - mpint K, the shared secret - - This value is called the exchange hash, and it is used to - authenticate the key exchange. The exchange hash SHOULD be kept - secret. - - - The signature algorithm MUST be applied over H, not the original - data. Most signature algorithms include hashing and additional - padding. For example, "ssh-dss" specifies SHA-1 hashing; in that - case, the data is first hashed with HASH to compute H, and H is then - hashed with SHA-1 as part of the signing operation. - -7.1 diffie-hellman-group1-sha1 - - The "diffie-hellman-group1-sha1" method specifies Diffie-Hellman key - exchange with SHA-1 as HASH, and Oakley group 14 [RFC3526] (2048-bit - MODP Group). It is included below in hexadecimal and decimal. - - The prime p is equal to 2^1024 - 2^960 - 1 + 2^64 * floor( 2^894 Pi + - 129093 ). Its hexadecimal value is: - - FFFFFFFF FFFFFFFF C90FDAA2 2168C234 C4C6628B 80DC1CD1 - 29024E08 8A67CC74 020BBEA6 3B139B22 514A0879 8E3404DD - EF9519B3 CD3A431B 302B0A6D F25F1437 4FE1356D 6D51C245 - E485B576 625E7EC6 F44C42E9 A637ED6B 0BFF5CB6 F406B7ED - EE386BFB 5A899FA5 AE9F2411 7C4B1FE6 49286651 ECE65381 - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 19] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - - FFFFFFFF FFFFFFFF. - - In decimal, this value is: - - 179769313486231590770839156793787453197860296048756011706444 - 423684197180216158519368947833795864925541502180565485980503 - 646440548199239100050792877003355816639229553136239076508735 - 759914822574862575007425302077447712589550957937778424442426 - 617334727629299387668709205606050270810842907692932019128194 - 467627007. - - The generator used with this prime is g = 2. The group order q is (p - - 1) / 2. - -8. Key Re-Exchange - - Key re-exchange is started by sending an SSH_MSG_KEXINIT packet when - not already doing a key exchange (as described in Section Section - 6.1). When this message is received, a party MUST respond with its - own SSH_MSG_KEXINIT message except when the received SSH_MSG_KEXINIT - already was a reply. Either party MAY initiate the re-exchange, but - roles MUST NOT be changed (i.e., the server remains the server, and - the client remains the client). - - - Key re-exchange is performed using whatever encryption was in effect - when the exchange was started. Encryption, compression, and MAC - methods are not changed before a new SSH_MSG_NEWKEYS is sent after - the key exchange (as in the initial key exchange). Re-exchange is - processed identically to the initial key exchange, except for the - session identifier that will remain unchanged. It is permissible to - change some or all of the algorithms during the re-exchange. Host - keys can also change. All keys and initialization vectors are - recomputed after the exchange. Compression and encryption contexts - are reset. - - - It is recommended that the keys are changed after each gigabyte of - transmitted data or after each hour of connection time, whichever - comes sooner. However, since the re-exchange is a public key - operation, it requires a fair amount of processing power and should - not be performed too often. - - - More application data may be sent after the SSH_MSG_NEWKEYS packet - has been sent; key exchange does not affect the protocols that lie - above the SSH transport layer. - - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 20] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - -9. Service Request - - After the key exchange, the client requests a service. The service is - identified by a name. The format of names and procedures for defining - new names are defined in [SSH-ARCH]. - - - Currently, the following names have been reserved: - - ssh-userauth - ssh-connection - - Similar local naming policy is applied to the service names, as is - applied to the algorithm names; a local service should use the - "servicename@domain" syntax. - - byte SSH_MSG_SERVICE_REQUEST - string service name - - If the server rejects the service request, it SHOULD send an - appropriate SSH_MSG_DISCONNECT message and MUST disconnect. - - - When the service starts, it may have access to the session identifier - generated during the key exchange. - - - If the server supports the service (and permits the client to use - it), it MUST respond with the following: - - byte SSH_MSG_SERVICE_ACCEPT - string service name - - Message numbers used by services should be in the area reserved for - them (see Section 6 in [SSH-ARCH]). The transport level will - continue to process its own messages. - - - Note that after a key exchange with implicit server authentication, - the client MUST wait for response to its service request message - before sending any further data. - -10. Additional Messages - - Either party may send any of the following messages at any time. - - - - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 21] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - -10.1 Disconnection Message - - byte SSH_MSG_DISCONNECT - uint32 reason code - string description [RFC2279] - string language tag [RFC3066] - - This message causes immediate termination of the connection. All - implementations MUST be able to process this message; they SHOULD be - able to send this message. - - The sender MUST NOT send or receive any data after this message, and - the recipient MUST NOT accept any data after receiving this message. - The description field gives a more specific explanation in a - human-readable form. The error code gives the reason in a more - machine-readable format (suitable for localization), and can have the - following values: - - #define SSH_DISCONNECT_HOST_NOT_ALLOWED_TO_CONNECT 1 - #define SSH_DISCONNECT_PROTOCOL_ERROR 2 - #define SSH_DISCONNECT_KEY_EXCHANGE_FAILED 3 - #define SSH_DISCONNECT_RESERVED 4 - #define SSH_DISCONNECT_MAC_ERROR 5 - #define SSH_DISCONNECT_COMPRESSION_ERROR 6 - #define SSH_DISCONNECT_SERVICE_NOT_AVAILABLE 7 - #define SSH_DISCONNECT_PROTOCOL_VERSION_NOT_SUPPORTED 8 - #define SSH_DISCONNECT_HOST_KEY_NOT_VERIFIABLE 9 - #define SSH_DISCONNECT_CONNECTION_LOST 10 - #define SSH_DISCONNECT_BY_APPLICATION 11 - #define SSH_DISCONNECT_TOO_MANY_CONNECTIONS 12 - #define SSH_DISCONNECT_AUTH_CANCELLED_BY_USER 13 - #define SSH_DISCONNECT_NO_MORE_AUTH_METHODS_AVAILABLE 14 - #define SSH_DISCONNECT_ILLEGAL_USER_NAME 15 - - If the description string is displayed, control character filtering - discussed in [SSH-ARCH] should be used to avoid attacks by sending - terminal control characters. - -10.2 Ignored Data Message - - byte SSH_MSG_IGNORE - string data - - All implementations MUST understand (and ignore) this message at any - time (after receiving the protocol version). No implementation is - required to send them. This message can be used as an additional - protection measure against advanced traffic analysis techniques. - - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 22] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - -10.3 Debug Message - - byte SSH_MSG_DEBUG - boolean always_display - string message [RFC2279] - string language tag [RFC3066] - - All implementations MUST understand this message, but they are - allowed to ignore it. This message is used to pass the other side - information that may help debugging. If always_display is TRUE, the - message SHOULD be displayed. Otherwise, it SHOULD NOT be displayed - unless debugging information has been explicitly requested by the - user. - - - The message doesn't need to contain a newline. It is, however, - allowed to consist of multiple lines separated by CRLF (Carriage - Return - Line Feed) pairs. - - - If the message string is displayed, terminal control character - filtering discussed in [SSH-ARCH] should be used to avoid attacks by - sending terminal control characters. - -10.4 Reserved Messages - - An implementation MUST respond to all unrecognized messages with an - SSH_MSG_UNIMPLEMENTED message in the order in which the messages were - received. Such messages MUST be otherwise ignored. Later protocol - versions may define other meanings for these message types. - - byte SSH_MSG_UNIMPLEMENTED - uint32 packet sequence number of rejected message - - -11. Summary of Message Numbers - - The following message numbers have been defined in this protocol: - - #define SSH_MSG_DISCONNECT 1 - #define SSH_MSG_IGNORE 2 - #define SSH_MSG_UNIMPLEMENTED 3 - #define SSH_MSG_DEBUG 4 - #define SSH_MSG_SERVICE_REQUEST 5 - #define SSH_MSG_SERVICE_ACCEPT 6 - - #define SSH_MSG_KEXINIT 20 - #define SSH_MSG_NEWKEYS 21 - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 23] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - - /* Numbers 30-49 used for kex packets. - Different kex methods may reuse message numbers in - this range. */ - - #define SSH_MSG_KEXDH_INIT 30 - #define SSH_MSG_KEXDH_REPLY 31 - - -12. IANA Considerations - - This document is part of a set, the IANA considerations for the SSH - protocol as defined in [SSH-ARCH], [SSH-TRANS], [SSH-USERAUTH], - [SSH-CONNECT] are detailed in [SSH-NUMBERS]. - -13. Security Considerations - - This protocol provides a secure encrypted channel over an insecure - network. It performs server host authentication, key exchange, - encryption, and integrity protection. It also derives a unique - session id that may be used by higher-level protocols. - - Full security considerations for this protocol are provided in - Section 8 of [SSH-ARCH] - -14. Intellectual Property - - The IETF takes no position regarding the validity or scope of any - intellectual property 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; neither does it represent that it - has made any effort to identify any such rights. Information on the - IETF's procedures with respect to rights in standards-track and - standards-related documentation can be found in BCP-11. Copies of - claims of rights made available for publication 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 Secretariat. - - The IETF has been notified of intellectual property rights claimed in - regard to some or all of the specification contained in this - document. For more information consult the online list of claimed - rights. - -15. Additional Information - - The current document editor is: [email protected]. Comments on - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 24] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - - this internet draft should be sent to the IETF SECSH working group, - details at: http://ietf.org/html.charters/secsh-charter.html - -Normative - - [SSH-ARCH] - Ylonen, T., "SSH Protocol Architecture", I-D - draft-ietf-architecture-15.txt, Oct 2003. - - [SSH-TRANS] - Ylonen, T., "SSH Transport Layer Protocol", I-D - draft-ietf-transport-17.txt, Oct 2003. - - [SSH-USERAUTH] - Ylonen, T., "SSH Authentication Protocol", I-D - draft-ietf-userauth-18.txt, Oct 2003. - - [SSH-CONNECT] - Ylonen, T., "SSH Connection Protocol", I-D - draft-ietf-connect-18.txt, Oct 2003. - - [SSH-NUMBERS] - Lehtinen, S. and D. Moffat, "SSH Protocol Assigned - Numbers", I-D draft-ietf-secsh-assignednumbers-05.txt, Oct - 2003. - - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - -Informative - - [FIPS-186] - Federal Information Processing Standards Publication, - "FIPS PUB 186, Digital Signature Standard", May 1994. - - [FIPS-197] - NIST, "FIPS PUB 197 Advanced Encryption Standard (AES)", - November 2001. - - [FIPS-46-3] - U.S. Dept. of Commerce, "FIPS PUB 46-3, Data Encryption - Standard (DES)", October 1999. - - [RFC2459] Housley, R., Ford, W., Polk, T. and D. Solo, "Internet - X.509 Public Key Infrastructure Certificate and CRL - Profile", RFC 2459, January 1999. - - [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 25] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - - STD 13, RFC 1034, November 1987. - - [RFC3066] Alvestrand, H., "Tags for the Identification of - Languages", BCP 47, RFC 3066, January 2001. - - [RFC1950] Deutsch, L. and J-L. Gailly, "ZLIB Compressed Data Format - Specification version 3.3", RFC 1950, May 1996. - - [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification - version 1.3", RFC 1951, May 1996. - - [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO - 10646", RFC 2279, January 1998. - - [RFC2104] Krawczyk, H., Bellare, M. and R. Canetti, "HMAC: - Keyed-Hashing for Message Authentication", RFC 2104, - February 1997. - - [RFC2144] Adams, C., "The CAST-128 Encryption Algorithm", RFC 2144, - May 1997. - - [RFC2440] Callas, J., Donnerhacke, L., Finney, H. and R. Thayer, - "OpenPGP Message Format", RFC 2440, November 1998. - - [RFC2693] Ellison, C., Frantz, B., Lampson, B., Rivest, R., Thomas, - B. and T. Ylonen, "SPKI Certificate Theory", RFC 2693, - September 1999. - - [RFC3526] Kivinen, T. and M. Kojo, "More Modular Exponential (MODP) - Diffie-Hellman groups for Internet Key Exchange (IKE)", - RFC 3526, May 2003. - - [SCHNEIER] - Schneier, B., "Applied Cryptography Second Edition: - protocols algorithms and source in code in C", 1996. - - [TWOFISH] Schneier, B., "The Twofish Encryptions Algorithm: A - 128-Bit Block Cipher, 1st Edition", March 1999. - - - - - - - - - - - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 26] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - -Authors' Addresses - - Tatu Ylonen - SSH Communications Security Corp - Fredrikinkatu 42 - HELSINKI FIN-00100 - Finland - - EMail: [email protected] - - - Darren J. Moffat (editor) - Sun Microsystems, Inc - 17 Network Circle - Menlo Park 95025 - USA - - EMail: [email protected] - -Appendix A. Contibutors - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 27] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - -Intellectual Property Statement - - The IETF takes no position regarding the validity or scope of any - intellectual property 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; neither does it represent that it - has made any effort to identify any such rights. Information on the - IETF's procedures with respect to rights in standards-track and - standards-related documentation can be found in BCP-11. Copies of - claims of rights made available for publication 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 implementors or users of this specification can - be obtained from the IETF Secretariat. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights which may cover technology that may be required to practice - this standard. Please address the information to the IETF Executive - Director. - - The IETF has been notified of intellectual property rights claimed in - regard to some or all of the specification contained in this - document. For more information consult the online list of claimed - rights. - - -Full Copyright Statement - - Copyright (C) The Internet Society (2003). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assignees. - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 28] - -Internet-Draft SSH Transport Layer Protocol Oct 2003 - - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS 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. - - -Acknowledgment - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Ylonen & Moffat, Editor Expires March 31, 2004 [Page 29]
\ No newline at end of file diff --git a/lib/ssh/doc/standard/draft-ietf-secsh-userauth-18.2.ps b/lib/ssh/doc/standard/draft-ietf-secsh-userauth-18.2.ps deleted file mode 100644 index be5799dbce..0000000000 --- a/lib/ssh/doc/standard/draft-ietf-secsh-userauth-18.2.ps +++ /dev/null @@ -1,1881 +0,0 @@ -%!PS-Adobe-3.0 -%%BoundingBox: 75 0 595 747 -%%Title: Enscript Output -%%For: Magnus Thoang -%%Creator: GNU enscript 1.6.1 -%%CreationDate: Fri Oct 31 13:35:32 2003 -%%Orientation: Portrait -%%Pages: 8 0 -%%DocumentMedia: A4 595 842 0 () () -%%DocumentNeededResources: (atend) -%%EndComments -%%BeginProlog -%%BeginProcSet: PStoPS 1 15 -userdict begin -[/showpage/erasepage/copypage]{dup where{pop dup load - type/operatortype eq{1 array cvx dup 0 3 index cvx put - bind def}{pop}ifelse}{pop}ifelse}forall -[/letter/legal/executivepage/a4/a4small/b5/com10envelope - /monarchenvelope/c5envelope/dlenvelope/lettersmall/note - /folio/quarto/a5]{dup where{dup wcheck{exch{}put} - {pop{}def}ifelse}{pop}ifelse}forall -/setpagedevice {pop}bind 1 index where{dup wcheck{3 1 roll put} - {pop def}ifelse}{def}ifelse -/PStoPSmatrix matrix currentmatrix def -/PStoPSxform matrix def/PStoPSclip{clippath}def -/defaultmatrix{PStoPSmatrix exch PStoPSxform exch concatmatrix}bind def -/initmatrix{matrix defaultmatrix setmatrix}bind def -/initclip[{matrix currentmatrix PStoPSmatrix setmatrix - [{currentpoint}stopped{$error/newerror false put{newpath}} - {/newpath cvx 3 1 roll/moveto cvx 4 array astore cvx}ifelse] - {[/newpath cvx{/moveto cvx}{/lineto cvx} - {/curveto cvx}{/closepath cvx}pathforall]cvx exch pop} - stopped{$error/errorname get/invalidaccess eq{cleartomark - $error/newerror false put cvx exec}{stop}ifelse}if}bind aload pop - /initclip dup load dup type dup/operatortype eq{pop exch pop} - {dup/arraytype eq exch/packedarraytype eq or - {dup xcheck{exch pop aload pop}{pop cvx}ifelse} - {pop cvx}ifelse}ifelse - {newpath PStoPSclip clip newpath exec setmatrix} bind aload pop]cvx def -/initgraphics{initmatrix newpath initclip 1 setlinewidth - 0 setlinecap 0 setlinejoin []0 setdash 0 setgray - 10 setmiterlimit}bind def -end -%%EndProcSet -%%BeginResource: procset Enscript-Prolog 1.6 1 -% -% Procedures. -% - -/_S { % save current state - /_s save def -} def -/_R { % restore from saved state - _s restore -} def - -/S { % showpage protecting gstate - gsave - showpage - grestore -} bind def - -/MF { % fontname newfontname -> - make a new encoded font - /newfontname exch def - /fontname exch def - - /fontdict fontname findfont def - /newfont fontdict maxlength dict def - - fontdict { - exch - dup /FID eq { - % skip FID pair - pop pop - } { - % copy to the new font dictionary - exch newfont 3 1 roll put - } ifelse - } forall - - newfont /FontName newfontname put - - % insert only valid encoding vectors - encoding_vector length 256 eq { - newfont /Encoding encoding_vector put - } if - - newfontname newfont definefont pop -} def - -/SF { % fontname width height -> - set a new font - /height exch def - /width exch def - - findfont - [width 0 0 height 0 0] makefont setfont -} def - -/SUF { % fontname width height -> - set a new user font - /height exch def - /width exch def - - /F-gs-user-font MF - /F-gs-user-font width height SF -} def - -/M {moveto} bind def -/s {show} bind def - -/Box { % x y w h -> - define box path - /d_h exch def /d_w exch def /d_y exch def /d_x exch def - d_x d_y moveto - d_w 0 rlineto - 0 d_h rlineto - d_w neg 0 rlineto - closepath -} def - -/bgs { % x y height blskip gray str -> - show string with bg color - /str exch def - /gray exch def - /blskip exch def - /height exch def - /y exch def - /x exch def - - gsave - x y blskip sub str stringwidth pop height Box - gray setgray - fill - grestore - x y M str s -} def - -% Highlight bars. -/highlight_bars { % nlines lineheight output_y_margin gray -> - - gsave - setgray - /ymarg exch def - /lineheight exch def - /nlines exch def - - % This 2 is just a magic number to sync highlight lines to text. - 0 d_header_y ymarg sub 2 sub translate - - /cw d_output_w cols div def - /nrows d_output_h ymarg 2 mul sub lineheight div cvi def - - % for each column - 0 1 cols 1 sub { - cw mul /xp exch def - - % for each rows - 0 1 nrows 1 sub { - /rn exch def - rn lineheight mul neg /yp exch def - rn nlines idiv 2 mod 0 eq { - % Draw highlight bar. 4 is just a magic indentation. - xp 4 add yp cw 8 sub lineheight neg Box fill - } if - } for - } for - - grestore -} def - -% Line highlight bar. -/line_highlight { % x y width height gray -> - - gsave - /gray exch def - Box gray setgray fill - grestore -} def - -% Column separator lines. -/column_lines { - gsave - .1 setlinewidth - 0 d_footer_h translate - /cw d_output_w cols div def - 1 1 cols 1 sub { - cw mul 0 moveto - 0 d_output_h rlineto stroke - } for - grestore -} def - -% Column borders. -/column_borders { - gsave - .1 setlinewidth - 0 d_footer_h moveto - 0 d_output_h rlineto - d_output_w 0 rlineto - 0 d_output_h neg rlineto - closepath stroke - grestore -} def - -% Do the actual underlay drawing -/draw_underlay { - ul_style 0 eq { - ul_str true charpath stroke - } { - ul_str show - } ifelse -} def - -% Underlay -/underlay { % - -> - - gsave - 0 d_page_h translate - d_page_h neg d_page_w atan rotate - - ul_gray setgray - ul_font setfont - /dw d_page_h dup mul d_page_w dup mul add sqrt def - ul_str stringwidth pop dw exch sub 2 div ul_h_ptsize -2 div moveto - draw_underlay - grestore -} def - -/user_underlay { % - -> - - gsave - ul_x ul_y translate - ul_angle rotate - ul_gray setgray - ul_font setfont - 0 0 ul_h_ptsize 2 div sub moveto - draw_underlay - grestore -} def - -% Page prefeed -/page_prefeed { % bool -> - - statusdict /prefeed known { - statusdict exch /prefeed exch put - } { - pop - } ifelse -} def - -% Wrapped line markers -/wrapped_line_mark { % x y charwith charheight type -> - - /type exch def - /h exch def - /w exch def - /y exch def - /x exch def - - type 2 eq { - % Black boxes (like TeX does) - gsave - 0 setlinewidth - x w 4 div add y M - 0 h rlineto w 2 div 0 rlineto 0 h neg rlineto - closepath fill - grestore - } { - type 3 eq { - % Small arrows - gsave - .2 setlinewidth - x w 2 div add y h 2 div add M - w 4 div 0 rlineto - x w 4 div add y lineto stroke - - x w 4 div add w 8 div add y h 4 div add M - x w 4 div add y lineto - w 4 div h 8 div rlineto stroke - grestore - } { - % do nothing - } ifelse - } ifelse -} def - -% EPSF import. - -/BeginEPSF { - /b4_Inc_state save def % Save state for cleanup - /dict_count countdictstack def % Count objects on dict stack - /op_count count 1 sub def % Count objects on operand stack - userdict begin - /showpage { } def - 0 setgray 0 setlinecap - 1 setlinewidth 0 setlinejoin - 10 setmiterlimit [ ] 0 setdash newpath - /languagelevel where { - pop languagelevel - 1 ne { - false setstrokeadjust false setoverprint - } if - } if -} bind def - -/EndEPSF { - count op_count sub { pos } repeat % Clean up stacks - countdictstack dict_count sub { end } repeat - b4_Inc_state restore -} bind def - -% Check PostScript language level. -/languagelevel where { - pop /gs_languagelevel languagelevel def -} { - /gs_languagelevel 1 def -} ifelse -%%EndResource -%%BeginResource: procset Enscript-Encoding-88591 1.6 1 -/encoding_vector [ -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/space /exclam /quotedbl /numbersign -/dollar /percent /ampersand /quoteright -/parenleft /parenright /asterisk /plus -/comma /hyphen /period /slash -/zero /one /two /three -/four /five /six /seven -/eight /nine /colon /semicolon -/less /equal /greater /question -/at /A /B /C -/D /E /F /G -/H /I /J /K -/L /M /N /O -/P /Q /R /S -/T /U /V /W -/X /Y /Z /bracketleft -/backslash /bracketright /asciicircum /underscore -/quoteleft /a /b /c -/d /e /f /g -/h /i /j /k -/l /m /n /o -/p /q /r /s -/t /u /v /w -/x /y /z /braceleft -/bar /braceright /tilde /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/.notdef /.notdef /.notdef /.notdef -/space /exclamdown /cent /sterling -/currency /yen /brokenbar /section -/dieresis /copyright /ordfeminine /guillemotleft -/logicalnot /hyphen /registered /macron -/degree /plusminus /twosuperior /threesuperior -/acute /mu /paragraph /bullet -/cedilla /onesuperior /ordmasculine /guillemotright -/onequarter /onehalf /threequarters /questiondown -/Agrave /Aacute /Acircumflex /Atilde -/Adieresis /Aring /AE /Ccedilla -/Egrave /Eacute /Ecircumflex /Edieresis -/Igrave /Iacute /Icircumflex /Idieresis -/Eth /Ntilde /Ograve /Oacute -/Ocircumflex /Otilde /Odieresis /multiply -/Oslash /Ugrave /Uacute /Ucircumflex -/Udieresis /Yacute /Thorn /germandbls -/agrave /aacute /acircumflex /atilde -/adieresis /aring /ae /ccedilla -/egrave /eacute /ecircumflex /edieresis -/igrave /iacute /icircumflex /idieresis -/eth /ntilde /ograve /oacute -/ocircumflex /otilde /odieresis /divide -/oslash /ugrave /uacute /ucircumflex -/udieresis /yacute /thorn /ydieresis -] def -%%EndResource -%%EndProlog -%%BeginSetup -%%IncludeResource: font Courier-Bold -%%IncludeResource: font Courier -/HFpt_w 10 def -/HFpt_h 10 def -/Courier-Bold /HF-gs-font MF -/HF /HF-gs-font findfont [HFpt_w 0 0 HFpt_h 0 0] makefont def -/Courier /F-gs-font MF -/F-gs-font 10 10 SF -/#copies 1 def -/d_page_w 520 def -/d_page_h 747 def -/d_header_x 0 def -/d_header_y 747 def -/d_header_w 520 def -/d_header_h 0 def -/d_footer_x 0 def -/d_footer_y 0 def -/d_footer_w 520 def -/d_footer_h 0 def -/d_output_w 520 def -/d_output_h 747 def -/cols 1 def -userdict/PStoPSxform PStoPSmatrix matrix currentmatrix - matrix invertmatrix matrix concatmatrix - matrix invertmatrix put -%%EndSetup -%%Page: (0,1) 1 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 1 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 701 M -(Network Working Group T. Ylonen) s -5 690 M -(Internet-Draft SSH Communications Security Corp) s -5 679 M -(Expires: March 2, 2003 D. Moffat, Ed.) s -5 668 M -( Sun Microsystems, Inc) s -5 657 M -( September 2002) s -5 624 M -( SSH Authentication Protocol) s -5 613 M -( draft-ietf-secsh-userauth-18.txt) s -5 591 M -(Status of this Memo) s -5 569 M -( This document is an Internet-Draft and is in full conformance with) s -5 558 M -( all provisions of Section 10 of RFC2026.) s -5 536 M -( Internet-Drafts are working documents of the Internet Engineering) s -5 525 M -( Task Force \(IETF\), its areas, and its working groups. Note that other) s -5 514 M -( groups may also distribute working documents as Internet-Drafts.) s -5 492 M -( Internet-Drafts are draft documents valid for a maximum of six months) s -5 481 M -( and may be updated, replaced, or obsoleted by other documents at any) s -5 470 M -( time. It is inappropriate to use Internet-Drafts as reference) s -5 459 M -( material or to cite them other than as "work in progress.") s -5 437 M -( The list of current Internet-Drafts can be accessed at http://) s -5 426 M -( www.ietf.org/ietf/1id-abstracts.txt.) s -5 404 M -( The list of Internet-Draft Shadow Directories can be accessed at) s -5 393 M -( http://www.ietf.org/shadow.html.) s -5 371 M -( This Internet-Draft will expire on March 2, 2003.) s -5 349 M -(Copyright Notice) s -5 327 M -( Copyright \(C\) The Internet Society \(2002\). All Rights Reserved.) s -5 305 M -(Abstract) s -5 283 M -( SSH is a protocol for secure remote login and other secure network) s -5 272 M -( services over an insecure network. This document describes the SSH) s -5 261 M -( authentication protocol framework and public key, password, and) s -5 250 M -( host-based client authentication methods. Additional authentication) s -5 239 M -( methods are described in separate documents. The SSH authentication) s -5 228 M -( protocol runs on top of the SSH transport layer protocol and provides) s -5 217 M -( a single authenticated tunnel for the SSH connection protocol.) s -5 129 M -(Ylonen & Moffat Expires March 2, 2003 [Page 1]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 2 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Authentication Protocol September 2002) s -5 690 M -(Table of Contents) s -5 668 M -( 1. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 3) s -5 657 M -( 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3) s -5 646 M -( 3. Conventions Used in This Document . . . . . . . . . . . . . 3) s -5 635 M -( 3.1 The Authentication Protocol Framework . . . . . . . . . . . 3) s -5 624 M -( 3.1.1 Authentication Requests . . . . . . . . . . . . . . . . . . 4) s -5 613 M -( 3.1.2 Responses to Authentication Requests . . . . . . . . . . . . 5) s -5 602 M -( 3.1.3 The "none" Authentication Request . . . . . . . . . . . . . 6) s -5 591 M -( 3.1.4 Completion of User Authentication . . . . . . . . . . . . . 6) s -5 580 M -( 3.1.5 Banner Message . . . . . . . . . . . . . . . . . . . . . . . 7) s -5 569 M -( 3.2 Authentication Protocol Message Numbers . . . . . . . . . . 7) s -5 558 M -( 3.3 Public Key Authentication Method: publickey . . . . . . . . 8) s -5 547 M -( 3.4 Password Authentication Method: password . . . . . . . . . . 10) s -5 536 M -( 3.5 Host-Based Authentication: hostbased . . . . . . . . . . . . 11) s -5 525 M -( 4. Security Considerations . . . . . . . . . . . . . . . . . . 12) s -5 514 M -( Normative . . . . . . . . . . . . . . . . . . . . . . . . . 13) s -5 503 M -( Informative . . . . . . . . . . . . . . . . . . . . . . . . 13) s -5 492 M -( Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 14) s -5 481 M -( Intellectual Property and Copyright Statements . . . . . . . 15) s -5 129 M -(Ylonen & Moffat Expires March 2, 2003 [Page 2]) s -_R -S -PStoPSsaved restore -%%Page: (2,3) 2 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 3 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Authentication Protocol September 2002) s -5 690 M -(1. Contributors) s -5 668 M -( The major original contributors of this document were: Tatu Ylonen,) s -5 657 M -( Tero Kivinen, Timo J. Rinne, Sami Lehtinen \(all of SSH Communications) s -5 646 M -( Security Corp\), and Markku-Juhani O. Saarinen \(University of) s -5 635 M -( Jyvaskyla\)) s -5 613 M -( The document editor is: [email protected]. Comments on this) s -5 602 M -( internet draft should be sent to the IETF SECSH working group,) s -5 591 M -( details at: http://ietf.org/html.charters/secsh-charter.html) s -5 569 M -(2. Introduction) s -5 547 M -( The SSH authentication protocol is a general-purpose user) s -5 536 M -( authentication protocol. It is intended to be run over the SSH) s -5 525 M -( transport layer protocol [SSH-TRANS]. This protocol assumes that the) s -5 514 M -( underlying protocols provide integrity and confidentiality) s -5 503 M -( protection.) s -5 481 M -( This document should be read only after reading the SSH architecture) s -5 470 M -( document [SSH-ARCH]. This document freely uses terminology and) s -5 459 M -( notation from the architecture document without reference or further) s -5 448 M -( explanation.) s -5 426 M -( The service name for this protocol is "ssh-userauth".) s -5 404 M -( When this protocol starts, it receives the session identifier from) s -5 393 M -( the lower-level protocol \(this is the exchange hash H from the first) s -5 382 M -( key exchange\). The session identifier uniquely identifies this) s -5 371 M -( session and is suitable for signing in order to prove ownership of a) s -5 360 M -( private key. This protocol also needs to know whether the lower-level) s -5 349 M -( protocol provides confidentiality protection.) s -5 327 M -(3. Conventions Used in This Document) s -5 305 M -( The keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT",) s -5 294 M -( and "MAY" that appear in this document are to be interpreted as) s -5 283 M -( described in [RFC2119]) s -5 261 M -( The used data types and terminology are specified in the architecture) s -5 250 M -( document [SSH-ARCH]) s -5 228 M -( The architecture document also discusses the algorithm naming) s -5 217 M -( conventions that MUST be used with the SSH protocols.) s -5 195 M -(3.1 The Authentication Protocol Framework) s -5 173 M -( The server drives the authentication by telling the client which) s -5 129 M -(Ylonen & Moffat Expires March 2, 2003 [Page 3]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 4 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Authentication Protocol September 2002) s -5 690 M -( authentication methods can be used to continue the exchange at any) s -5 679 M -( given time. The client has the freedom to try the methods listed by) s -5 668 M -( the server in any order. This gives the server complete control over) s -5 657 M -( the authentication process if desired, but also gives enough) s -5 646 M -( flexibility for the client to use the methods it supports or that are) s -5 635 M -( most convenient for the user, when multiple methods are offered by) s -5 624 M -( the server.) s -5 602 M -( Authentication methods are identified by their name, as defined in) s -5 591 M -( [SSH-ARCH]. The "none" method is reserved, and MUST NOT be listed as) s -5 580 M -( supported. However, it MAY be sent by the client. The server MUST) s -5 569 M -( always reject this request, unless the client is to be allowed in) s -5 558 M -( without any authentication, in which case the server MUST accept this) s -5 547 M -( request. The main purpose of sending this request is to get the list) s -5 536 M -( of supported methods from the server.) s -5 514 M -( The server SHOULD have a timeout for authentication, and disconnect) s -5 503 M -( if the authentication has not been accepted within the timeout) s -5 492 M -( period. The RECOMMENDED timeout period is 10 minutes. Additionally,) s -5 481 M -( the implementation SHOULD limit the number of failed authentication) s -5 470 M -( attempts a client may perform in a single session \(the RECOMMENDED) s -5 459 M -( limit is 20 attempts\). If the threshold is exceeded, the server) s -5 448 M -( SHOULD disconnect.) s -5 426 M -(3.1.1 Authentication Requests) s -5 404 M -( All authentication requests MUST use the following message format.) s -5 393 M -( Only the first few fields are defined; the remaining fields depend on) s -5 382 M -( the authentication method.) s -5 360 M -( byte SSH_MSG_USERAUTH_REQUEST) s -5 349 M -( string user name \(in ISO-10646 UTF-8 encoding [RFC2279]\)) s -5 338 M -( string service name \(in US-ASCII\)) s -5 327 M -( string method name \(US-ASCII\)) s -5 316 M -( The rest of the packet is method-specific.) s -5 294 M -( The user name and service are repeated in every new authentication) s -5 283 M -( attempt, and MAY change. The server implementation MUST carefully) s -5 272 M -( check them in every message, and MUST flush any accumulated) s -5 261 M -( authentication states if they change. If it is unable to flush some) s -5 250 M -( authentication state, it MUST disconnect if the user or service name) s -5 239 M -( changes.) s -5 217 M -( The service name specifies the service to start after authentication.) s -5 206 M -( There may be several different authenticated services provided. If) s -5 195 M -( the requested service is not available, the server MAY disconnect) s -5 184 M -( immediately or at any later time. Sending a proper disconnect) s -5 173 M -( message is RECOMMENDED. In any case, if the service does not exist,) s -5 129 M -(Ylonen & Moffat Expires March 2, 2003 [Page 4]) s -_R -S -PStoPSsaved restore -%%Page: (4,5) 3 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 5 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Authentication Protocol September 2002) s -5 690 M -( authentication MUST NOT be accepted.) s -5 668 M -( If the requested user does not exist, the server MAY disconnect, or) s -5 657 M -( MAY send a bogus list of acceptable authentication methods, but never) s -5 646 M -( accept any. This makes it possible for the server to avoid) s -5 635 M -( disclosing information on which accounts exist. In any case, if the) s -5 624 M -( user does not exist, the authentication request MUST NOT be accepted.) s -5 602 M -( While there is usually little point for clients to send requests that) s -5 591 M -( the server does not list as acceptable, sending such requests is not) s -5 580 M -( an error, and the server SHOULD simply reject requests that it does) s -5 569 M -( not recognize.) s -5 547 M -( An authentication request MAY result in a further exchange of) s -5 536 M -( messages. All such messages depend on the authentication method) s -5 525 M -( used, and the client MAY at any time continue with a new) s -5 514 M -( SSH_MSG_USERAUTH_REQUEST message, in which case the server MUST) s -5 503 M -( abandon the previous authentication attempt and continue with the new) s -5 492 M -( one.) s -5 470 M -(3.1.2 Responses to Authentication Requests) s -5 448 M -( If the server rejects the authentication request, it MUST respond) s -5 437 M -( with the following:) s -5 415 M -( byte SSH_MSG_USERAUTH_FAILURE) s -5 404 M -( string authentications that can continue) s -5 393 M -( boolean partial success) s -5 371 M -( "Authentications that can continue" is a comma-separated list of) s -5 360 M -( authentication method names that may productively continue the) s -5 349 M -( authentication dialog.) s -5 327 M -( It is RECOMMENDED that servers only include those methods in the list) s -5 316 M -( that are actually useful. However, it is not illegal to include) s -5 305 M -( methods that cannot be used to authenticate the user.) s -5 283 M -( Already successfully completed authentications SHOULD NOT be included) s -5 272 M -( in the list, unless they really should be performed again for some) s -5 261 M -( reason.) s -5 239 M -( "Partial success" MUST be TRUE if the authentication request to which) s -5 228 M -( this is a response was successful. It MUST be FALSE if the request) s -5 217 M -( was not successfully processed.) s -5 195 M -( When the server accepts authentication, it MUST respond with the) s -5 184 M -( following:) s -5 129 M -(Ylonen & Moffat Expires March 2, 2003 [Page 5]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 6 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Authentication Protocol September 2002) s -5 690 M -( byte SSH_MSG_USERAUTH_SUCCESS) s -5 668 M -( Note that this is not sent after each step in a multi-method) s -5 657 M -( authentication sequence, but only when the authentication is) s -5 646 M -( complete.) s -5 624 M -( The client MAY send several authentication requests without waiting) s -5 613 M -( for responses from previous requests. The server MUST process each) s -5 602 M -( request completely and acknowledge any failed requests with a) s -5 591 M -( SSH_MSG_USERAUTH_FAILURE message before processing the next request.) s -5 569 M -( A request that results in further exchange of messages will be) s -5 558 M -( aborted by a second request. It is not possible to send a second) s -5 547 M -( request without waiting for a response from the server, if the first) s -5 536 M -( request will result in further exchange of messages. No) s -5 525 M -( SSH_MSG_USERAUTH_FAILURE message will be sent for the aborted method.) s -5 503 M -( SSH_MSG_USERAUTH_SUCCESS MUST be sent only once. When) s -5 492 M -( SSH_MSG_USERAUTH_SUCCESS has been sent, any further authentication) s -5 481 M -( requests received after that SHOULD be silently ignored.) s -5 459 M -( Any non-authentication messages sent by the client after the request) s -5 448 M -( that resulted in SSH_MSG_USERAUTH_SUCCESS being sent MUST be passed) s -5 437 M -( to the service being run on top of this protocol. Such messages can) s -5 426 M -( be identified by their message numbers \(see Section Message Numbers) s -5 415 M -( \(Section 3.2\)\).) s -5 393 M -(3.1.3 The "none" Authentication Request) s -5 371 M -( A client may request a list of authentication methods that may) s -5 360 M -( continue by using the "none" authentication method.) s -5 338 M -( If no authentication at all is needed for the user, the server MUST) s -5 327 M -( return SSH_MSG_USERAUTH_SUCCESS. Otherwise, the server MUST return) s -5 316 M -( SSH_MSG_USERAUTH_FAILURE and MAY return with it a list of) s -5 305 M -( authentication methods that can continue.) s -5 283 M -( This method MUST NOT be listed as supported by the server.) s -5 261 M -(3.1.4 Completion of User Authentication) s -5 239 M -( Authentication is complete when the server has responded with) s -5 228 M -( SSH_MSG_USERAUTH_SUCCESS; all authentication related messages) s -5 217 M -( received after sending this message SHOULD be silently ignored.) s -5 195 M -( After sending SSH_MSG_USERAUTH_SUCCESS, the server starts the) s -5 184 M -( requested service.) s -5 129 M -(Ylonen & Moffat Expires March 2, 2003 [Page 6]) s -_R -S -PStoPSsaved restore -%%Page: (6,7) 4 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 7 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Authentication Protocol September 2002) s -5 690 M -(3.1.5 Banner Message) s -5 668 M -( In some jurisdictions, sending a warning message before) s -5 657 M -( authentication may be relevant for getting legal protection. Many) s -5 646 M -( UNIX machines, for example, normally display text from `/etc/issue',) s -5 635 M -( or use "tcp wrappers" or similar software to display a banner before) s -5 624 M -( issuing a login prompt.) s -5 602 M -( The SSH server may send a SSH_MSG_USERAUTH_BANNER message at any time) s -5 591 M -( before authentication is successful. This message contains text to) s -5 580 M -( be displayed to the client user before authentication is attempted.) s -5 569 M -( The format is as follows:) s -5 547 M -( byte SSH_MSG_USERAUTH_BANNER) s -5 536 M -( string message \(ISO-10646 UTF-8\)) s -5 525 M -( string language tag \(as defined in [RFC3066]\)) s -5 503 M -( The client SHOULD by default display the message on the screen.) s -5 492 M -( However, since the message is likely to be sent for every login) s -5 481 M -( attempt, and since some client software will need to open a separate) s -5 470 M -( window for this warning, the client software may allow the user to) s -5 459 M -( explicitly disable the display of banners from the server. The) s -5 448 M -( message may consist of multiple lines.) s -5 426 M -( If the message string is displayed, control character filtering) s -5 415 M -( discussed in [SSH-ARCH] SHOULD be used to avoid attacks by sending) s -5 404 M -( terminal control characters.) s -5 382 M -(3.2 Authentication Protocol Message Numbers) s -5 360 M -( All message numbers used by this authentication protocol are in the) s -5 349 M -( range from 50 to 79, which is part of the range reserved for) s -5 338 M -( protocols running on top of the SSH transport layer protocol.) s -5 316 M -( Message numbers of 80 and higher are reserved for protocols running) s -5 305 M -( after this authentication protocol, so receiving one of them before) s -5 294 M -( authentication is complete is an error, to which the server MUST) s -5 283 M -( respond by disconnecting \(preferably with a proper disconnect message) s -5 272 M -( sent first to ease troubleshooting\).) s -5 250 M -( After successful authentication, such messages are passed to the) s -5 239 M -( higher-level service.) s -5 217 M -( These are the general authentication message codes:) s -5 195 M -( #define SSH_MSG_USERAUTH_REQUEST 50) s -5 184 M -( #define SSH_MSG_USERAUTH_FAILURE 51) s -5 173 M -( #define SSH_MSG_USERAUTH_SUCCESS 52) s -5 129 M -(Ylonen & Moffat Expires March 2, 2003 [Page 7]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 8 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Authentication Protocol September 2002) s -5 690 M -( #define SSH_MSG_USERAUTH_BANNER 53) s -5 668 M -( In addition to the above, there is a range of message numbers) s -5 657 M -( \(60..79\) reserved for method-specific messages. These messages are) s -5 646 M -( only sent by the server \(client sends only SSH_MSG_USERAUTH_REQUEST) s -5 635 M -( messages\). Different authentication methods reuse the same message) s -5 624 M -( numbers.) s -5 602 M -(3.3 Public Key Authentication Method: publickey) s -5 580 M -( The only REQUIRED authentication method is public key authentication.) s -5 569 M -( All implementations MUST support this method; however, not all users) s -5 558 M -( need to have public keys, and most local policies are not likely to) s -5 547 M -( require public key authentication for all users in the near future.) s -5 525 M -( With this method, the possession of a private key serves as) s -5 514 M -( authentication. This method works by sending a signature created) s -5 503 M -( with a private key of the user. The server MUST check that the key) s -5 492 M -( is a valid authenticator for the user, and MUST check that the) s -5 481 M -( signature is valid. If both hold, the authentication request MUST be) s -5 470 M -( accepted; otherwise it MUST be rejected. \(Note that the server MAY) s -5 459 M -( require additional authentications after successful authentication.\)) s -5 437 M -( Private keys are often stored in an encrypted form at the client) s -5 426 M -( host, and the user must supply a passphrase before the signature can) s -5 415 M -( be generated. Even if they are not, the signing operation involves) s -5 404 M -( some expensive computation. To avoid unnecessary processing and user) s -5 393 M -( interaction, the following message is provided for querying whether) s -5 382 M -( authentication using the key would be acceptable.) s -5 360 M -( byte SSH_MSG_USERAUTH_REQUEST) s -5 349 M -( string user name) s -5 338 M -( string service) s -5 327 M -( string "publickey") s -5 316 M -( boolean FALSE) s -5 305 M -( string public key algorithm name) s -5 294 M -( string public key blob) s -5 272 M -( Public key algorithms are defined in the transport layer) s -5 261 M -( specification [SSH-TRANS]. The public key blob may contain) s -5 250 M -( certificates.) s -5 228 M -( Any public key algorithm may be offered for use in authentication.) s -5 217 M -( In particular, the list is not constrained by what was negotiated) s -5 206 M -( during key exchange. If the server does not support some algorithm,) s -5 195 M -( it MUST simply reject the request.) s -5 173 M -( The server MUST respond to this message with either) s -5 129 M -(Ylonen & Moffat Expires March 2, 2003 [Page 8]) s -_R -S -PStoPSsaved restore -%%Page: (8,9) 5 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 9 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Authentication Protocol September 2002) s -5 690 M -( SSH_MSG_USERAUTH_FAILURE or with the following:) s -5 668 M -( byte SSH_MSG_USERAUTH_PK_OK) s -5 657 M -( string public key algorithm name from the request) s -5 646 M -( string public key blob from the request) s -5 624 M -( To perform actual authentication, the client MAY then send a) s -5 613 M -( signature generated using the private key. The client MAY send the) s -5 602 M -( signature directly without first verifying whether the key is) s -5 591 M -( acceptable. The signature is sent using the following packet:) s -5 569 M -( byte SSH_MSG_USERAUTH_REQUEST) s -5 558 M -( string user name) s -5 547 M -( string service) s -5 536 M -( string "publickey") s -5 525 M -( boolean TRUE) s -5 514 M -( string public key algorithm name) s -5 503 M -( string public key to be used for authentication) s -5 492 M -( string signature) s -5 470 M -( Signature is a signature by the corresponding private key over the) s -5 459 M -( following data, in the following order:) s -5 437 M -( string session identifier) s -5 426 M -( byte SSH_MSG_USERAUTH_REQUEST) s -5 415 M -( string user name) s -5 404 M -( string service) s -5 393 M -( string "publickey") s -5 382 M -( boolean TRUE) s -5 371 M -( string public key algorithm name) s -5 360 M -( string public key to be used for authentication) s -5 338 M -( When the server receives this message, it MUST check whether the) s -5 327 M -( supplied key is acceptable for authentication, and if so, it MUST) s -5 316 M -( check whether the signature is correct.) s -5 294 M -( If both checks succeed, this method is successful. Note that the) s -5 283 M -( server may require additional authentications. The server MUST) s -5 272 M -( respond with SSH_MSG_USERAUTH_SUCCESS \(if no more authentications are) s -5 261 M -( needed\), or SSH_MSG_USERAUTH_FAILURE \(if the request failed, or more) s -5 250 M -( authentications are needed\).) s -5 228 M -( The following method-specific message numbers are used by the) s -5 217 M -( publickey authentication method.) s -5 195 M -( /* Key-based */) s -5 184 M -( #define SSH_MSG_USERAUTH_PK_OK 60) s -5 129 M -(Ylonen & Moffat Expires March 2, 2003 [Page 9]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 10 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Authentication Protocol September 2002) s -5 690 M -(3.4 Password Authentication Method: password) s -5 668 M -( Password authentication uses the following packets. Note that a) s -5 657 M -( server MAY request the user to change the password. All) s -5 646 M -( implementations SHOULD support password authentication.) s -5 624 M -( byte SSH_MSG_USERAUTH_REQUEST) s -5 613 M -( string user name) s -5 602 M -( string service) s -5 591 M -( string "password") s -5 580 M -( boolean FALSE) s -5 569 M -( string plaintext password \(ISO-10646 UTF-8\)) s -5 547 M -( Note that the password is encoded in ISO-10646 UTF-8. It is up to) s -5 536 M -( the server how it interprets the password and validates it against) s -5 525 M -( the password database. However, if the client reads the password in) s -5 514 M -( some other encoding \(e.g., ISO 8859-1 \(ISO Latin1\)\), it MUST convert) s -5 503 M -( the password to ISO-10646 UTF-8 before transmitting, and the server) s -5 492 M -( MUST convert the password to the encoding used on that system for) s -5 481 M -( passwords.) s -5 459 M -( Note that even though the cleartext password is transmitted in the) s -5 448 M -( packet, the entire packet is encrypted by the transport layer. Both) s -5 437 M -( the server and the client should check whether the underlying) s -5 426 M -( transport layer provides confidentiality \(i.e., if encryption is) s -5 415 M -( being used\). If no confidentiality is provided \(none cipher\),) s -5 404 M -( password authentication SHOULD be disabled. If there is no) s -5 393 M -( confidentiality or no MAC, password change SHOULD be disabled.) s -5 371 M -( Normally, the server responds to this message with success or) s -5 360 M -( failure. However, if the password has expired the server SHOULD) s -5 349 M -( indicate this by responding with SSH_MSG_USERAUTH_PASSWD_CHANGEREQ.) s -5 338 M -( In anycase the server MUST NOT allow an expired password to be used) s -5 327 M -( for authentication.) s -5 305 M -( byte SSH_MSG_USERAUTH_PASSWD_CHANGEREQ) s -5 294 M -( string prompt \(ISO-10646 UTF-8\)) s -5 283 M -( string language tag \(as defined in [RFC3066]\)) s -5 261 M -( In this case, the client MAY continue with a different authentication) s -5 250 M -( method, or request a new password from the user and retry password) s -5 239 M -( authentication using the following message. The client MAY also send) s -5 228 M -( this message instead of the normal password authentication request) s -5 217 M -( without the server asking for it.) s -5 195 M -( byte SSH_MSG_USERAUTH_REQUEST) s -5 184 M -( string user name) s -5 173 M -( string service) s -5 129 M -(Ylonen & Moffat Expires March 2, 2003 [Page 10]) s -_R -S -PStoPSsaved restore -%%Page: (10,11) 6 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 11 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Authentication Protocol September 2002) s -5 690 M -( string "password") s -5 679 M -( boolean TRUE) s -5 668 M -( string plaintext old password \(ISO-10646 UTF-8\)) s -5 657 M -( string plaintext new password \(ISO-10646 UTF-8\)) s -5 635 M -( The server must reply to request message with) s -5 624 M -( SSH_MSG_USERAUTH_SUCCESS, SSH_MSG_USERAUTH_FAILURE, or another) s -5 613 M -( SSH_MSG_USERAUTH_PASSWD_CHANGEREQ. The meaning of these is as) s -5 602 M -( follows:) s -5 580 M -( SSH_MSG_USERAUTH_SUCCESS The password has been changed, and) s -5 569 M -( authentication has been successfully completed.) s -5 547 M -( SSH_MSG_USERAUTH_FAILURE with partial success The password has) s -5 536 M -( been changed, but more authentications are needed.) s -5 514 M -( SSH_MSG_USERAUTH_FAILURE without partial success The password has) s -5 503 M -( not been changed. Either password changing was not supported, or) s -5 492 M -( the old password was bad. Note that if the server has already) s -5 481 M -( sent SSH_MSG_USERAUTH_PASSWD_CHANGEREQ, we know that it supports) s -5 470 M -( changing the password.) s -5 448 M -( SSH_MSG_USERAUTH_CHANGEREQ The password was not changed because) s -5 437 M -( the new password was not acceptable \(e.g. too easy to guess\).) s -5 415 M -( The following method-specific message numbers are used by the) s -5 404 M -( password authentication method.) s -5 382 M -( #define SSH_MSG_USERAUTH_PASSWD_CHANGEREQ 60) s -5 349 M -(3.5 Host-Based Authentication: hostbased) s -5 327 M -( Some sites wish to allow authentication based on the host where the) s -5 316 M -( user is coming from, and the user name on the remote host. While) s -5 305 M -( this form of authentication is not suitable for high-security sites,) s -5 294 M -( it can be very convenient in many environments. This form of) s -5 283 M -( authentication is OPTIONAL. When used, special care SHOULD be taken) s -5 272 M -( to prevent a regular user from obtaining the private host key.) s -5 250 M -( The client requests this form of authentication by sending the) s -5 239 M -( following message. It is similar to the UNIX "rhosts" and) s -5 228 M -( "hosts.equiv" styles of authentication, except that the identity of) s -5 217 M -( the client host is checked more rigorously.) s -5 195 M -( This method works by having the client send a signature created with) s -5 184 M -( the private key of the client host, which the server checks with that) s -5 173 M -( host's public key. Once the client host's identity is established,) s -5 129 M -(Ylonen & Moffat Expires March 2, 2003 [Page 11]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 12 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Authentication Protocol September 2002) s -5 690 M -( authorization \(but no further authentication\) is performed based on) s -5 679 M -( the user names on the server and the client, and the client host) s -5 668 M -( name.) s -5 646 M -( byte SSH_MSG_USERAUTH_REQUEST) s -5 635 M -( string user name) s -5 624 M -( string service) s -5 613 M -( string "hostbased") s -5 602 M -( string public key algorithm for host key) s -5 591 M -( string public host key and certificates for client host) s -5 580 M -( string client host name \(FQDN; US-ASCII\)) s -5 569 M -( string user name on the client host \(ISO-10646 UTF-8\)) s -5 558 M -( string signature) s -5 536 M -( Public key algorithm names for use in "public key algorithm for host) s -5 525 M -( key" are defined in the transport layer specification. The "public) s -5 514 M -( host key for client host" may include certificates.) s -5 492 M -( Signature is a signature with the private host key of the following) s -5 481 M -( data, in this order:) s -5 459 M -( string session identifier) s -5 448 M -( byte SSH_MSG_USERAUTH_REQUEST) s -5 437 M -( string user name) s -5 426 M -( string service) s -5 415 M -( string "hostbased") s -5 404 M -( string public key algorithm for host key) s -5 393 M -( string public host key and certificates for client host) s -5 382 M -( string client host name \(FQDN; US-ASCII\)) s -5 371 M -( string user name on the client host\(ISO-10646 UTF-8\)) s -5 349 M -( The server MUST verify that the host key actually belongs to the) s -5 338 M -( client host named in the message, that the given user on that host is) s -5 327 M -( allowed to log in, and that the signature is a valid signature on the) s -5 316 M -( appropriate value by the given host key. The server MAY ignore the) s -5 305 M -( client user name, if it wants to authenticate only the client host.) s -5 283 M -( It is RECOMMENDED that whenever possible, the server perform) s -5 272 M -( additional checks to verify that the network address obtained from) s -5 261 M -( the \(untrusted\) network matches the given client host name. This) s -5 250 M -( makes exploiting compromised host keys more difficult. Note that) s -5 239 M -( this may require special handling for connections coming through a) s -5 228 M -( firewall.) s -5 206 M -(4. Security Considerations) s -5 184 M -( The purpose of this protocol is to perform client user) s -5 173 M -( authentication. It assumed that this runs over a secure transport) s -5 129 M -(Ylonen & Moffat Expires March 2, 2003 [Page 12]) s -_R -S -PStoPSsaved restore -%%Page: (12,13) 7 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 13 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Authentication Protocol September 2002) s -5 690 M -( layer protocol, which has already authenticated the server machine,) s -5 679 M -( established an encrypted communications channel, and computed a) s -5 668 M -( unique session identifier for this session. The transport layer) s -5 657 M -( provides forward secrecy for password authentication and other) s -5 646 M -( methods that rely on secret data.) s -5 624 M -( Full security considerations for this protocol are provided in) s -5 613 M -( Section 8 of [SSH-ARCH]) s -5 591 M -(Normative) s -5 569 M -( [SSH-ARCH]) s -5 558 M -( Ylonen, T., "SSH Protocol Architecture", I-D) s -5 547 M -( draft-ietf-architecture-15.txt, Oct 2003.) s -5 525 M -( [SSH-TRANS]) s -5 514 M -( Ylonen, T., "SSH Transport Layer Protocol", I-D) s -5 503 M -( draft-ietf-transport-17.txt, Oct 2003.) s -5 481 M -( [SSH-USERAUTH]) s -5 470 M -( Ylonen, T., "SSH Authentication Protocol", I-D) s -5 459 M -( draft-ietf-userauth-18.txt, Oct 2003.) s -5 437 M -( [SSH-CONNECT]) s -5 426 M -( Ylonen, T., "SSH Connection Protocol", I-D) s -5 415 M -( draft-ietf-connect-18.txt, Oct 2003.) s -5 393 M -( [SSH-NUMBERS]) s -5 382 M -( Lehtinen, S. and D. Moffat, "SSH Protocol Assigned) s -5 371 M -( Numbers", I-D draft-ietf-secsh-assignednumbers-05.txt, Oct) s -5 360 M -( 2003.) s -5 338 M -( [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate) s -5 327 M -( Requirement Levels", BCP 14, RFC 2119, March 1997.) s -5 305 M -(Informative) s -5 283 M -( [RFC3066] Alvestrand, H., "Tags for the Identification of) s -5 272 M -( Languages", BCP 47, RFC 3066, January 2001.) s -5 250 M -( [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO) s -5 239 M -( 10646", RFC 2279, January 1998.) s -5 129 M -(Ylonen & Moffat Expires March 2, 2003 [Page 13]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 14 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Authentication Protocol September 2002) s -5 690 M -(Authors' Addresses) s -5 668 M -( Tatu Ylonen) s -5 657 M -( SSH Communications Security Corp) s -5 646 M -( Fredrikinkatu 42) s -5 635 M -( HELSINKI FIN-00100) s -5 624 M -( Finland) s -5 602 M -( EMail: [email protected]) s -5 569 M -( Darren J. Moffat \(editor\)) s -5 558 M -( Sun Microsystems, Inc) s -5 547 M -( 17 Network Circle) s -5 536 M -( Menlo Park 95025) s -5 525 M -( USA) s -5 503 M -( EMail: [email protected]) s -5 129 M -(Ylonen & Moffat Expires March 2, 2003 [Page 14]) s -_R -S -PStoPSsaved restore -%%Page: (14,15) 8 -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 0.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -/showpage{}def/copypage{}def/erasepage{}def -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 15 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Authentication Protocol September 2002) s -5 690 M -(Intellectual Property Statement) s -5 668 M -( The IETF takes no position regarding the validity or scope of any) s -5 657 M -( intellectual property or other rights that might be claimed to) s -5 646 M -( pertain to the implementation or use of the technology described in) s -5 635 M -( this document or the extent to which any license under such rights) s -5 624 M -( might or might not be available; neither does it represent that it) s -5 613 M -( has made any effort to identify any such rights. Information on the) s -5 602 M -( IETF's procedures with respect to rights in standards-track and) s -5 591 M -( standards-related documentation can be found in BCP-11. Copies of) s -5 580 M -( claims of rights made available for publication and any assurances of) s -5 569 M -( licenses to be made available, or the result of an attempt made to) s -5 558 M -( obtain a general license or permission for the use of such) s -5 547 M -( proprietary rights by implementors or users of this specification can) s -5 536 M -( be obtained from the IETF Secretariat.) s -5 514 M -( The IETF invites any interested party to bring to its attention any) s -5 503 M -( copyrights, patents or patent applications, or other proprietary) s -5 492 M -( rights which may cover technology that may be required to practice) s -5 481 M -( this standard. Please address the information to the IETF Executive) s -5 470 M -( Director.) s -5 448 M -( The IETF has been notified of intellectual property rights claimed in) s -5 437 M -( regard to some or all of the specification contained in this) s -5 426 M -( document. For more information consult the online list of claimed) s -5 415 M -( rights.) s -5 382 M -(Full Copyright Statement) s -5 360 M -( Copyright \(C\) The Internet Society \(2002\). All Rights Reserved.) s -5 338 M -( This document and translations of it may be copied and furnished to) s -5 327 M -( others, and derivative works that comment on or otherwise explain it) s -5 316 M -( or assist in its implementation may be prepared, copied, published) s -5 305 M -( and distributed, in whole or in part, without restriction of any) s -5 294 M -( kind, provided that the above copyright notice and this paragraph are) s -5 283 M -( included on all such copies and derivative works. However, this) s -5 272 M -( document itself may not be modified in any way, such as by removing) s -5 261 M -( the copyright notice or references to the Internet Society or other) s -5 250 M -( Internet organizations, except as needed for the purpose of) s -5 239 M -( developing Internet standards in which case the procedures for) s -5 228 M -( copyrights defined in the Internet Standards process must be) s -5 217 M -( followed, or as required to translate it into languages other than) s -5 206 M -( English.) s -5 184 M -( The limited permissions granted above are perpetual and will not be) s -5 173 M -( revoked by the Internet Society or its successors or assignees.) s -5 129 M -(Ylonen & Moffat Expires March 2, 2003 [Page 15]) s -_R -S -PStoPSsaved restore -userdict/PStoPSsaved save put -PStoPSmatrix setmatrix -595.000000 421.271378 translate -90 rotate -0.706651 dup scale -userdict/PStoPSmatrix matrix currentmatrix put -userdict/PStoPSclip{0 0 moveto - 595.000000 0 rlineto 0 842.000000 rlineto -595.000000 0 rlineto - closepath}put initclip -PStoPSxform concat -%%BeginPageSetup -_S -75 0 translate -/pagenum 16 def -/fname () def -/fdir () def -/ftail () def -/user_header_p false def -%%EndPageSetup -5 723 M -(Internet-Draft SSH Authentication Protocol September 2002) s -5 690 M -( This document and the information contained herein is provided on an) s -5 679 M -( "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING) s -5 668 M -( TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING) s -5 657 M -( BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION) s -5 646 M -( HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF) s -5 635 M -( MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.) s -5 602 M -(Acknowledgment) s -5 580 M -( Funding for the RFC Editor function is currently provided by the) s -5 569 M -( Internet Society.) s -5 129 M -(Ylonen & Moffat Expires March 2, 2003 [Page 16]) s -_R -S -PStoPSsaved restore -%%Trailer -%%Pages: 16 -%%DocumentNeededResources: font Courier-Bold Courier -%%EOF diff --git a/lib/ssh/doc/standard/draft-ietf-secsh-userauth-18.txt b/lib/ssh/doc/standard/draft-ietf-secsh-userauth-18.txt deleted file mode 100644 index 9dae578a35..0000000000 --- a/lib/ssh/doc/standard/draft-ietf-secsh-userauth-18.txt +++ /dev/null @@ -1,896 +0,0 @@ - - - -Network Working Group T. Ylonen -Internet-Draft SSH Communications Security Corp -Expires: March 2, 2003 D. Moffat, Ed. - Sun Microsystems, Inc - September 2002 - - - SSH Authentication Protocol - draft-ietf-secsh-userauth-18.txt - -Status of this Memo - - This document is an Internet-Draft and is in full conformance with - all provisions of Section 10 of RFC2026. - - Internet-Drafts are working documents of the Internet Engineering - Task Force (IETF), its areas, and its working groups. Note that other - groups may also distribute working documents as Internet-Drafts. - - Internet-Drafts are draft documents valid for a maximum of six months - and may be updated, replaced, or obsoleted by other documents at any - time. It is inappropriate to use Internet-Drafts as reference - material or to cite them other than as "work in progress." - - The list of current Internet-Drafts can be accessed at http:// - www.ietf.org/ietf/1id-abstracts.txt. - - The list of Internet-Draft Shadow Directories can be accessed at - http://www.ietf.org/shadow.html. - - This Internet-Draft will expire on March 2, 2003. - -Copyright Notice - - Copyright (C) The Internet Society (2002). All Rights Reserved. - -Abstract - - SSH is a protocol for secure remote login and other secure network - services over an insecure network. This document describes the SSH - authentication protocol framework and public key, password, and - host-based client authentication methods. Additional authentication - methods are described in separate documents. The SSH authentication - protocol runs on top of the SSH transport layer protocol and provides - a single authenticated tunnel for the SSH connection protocol. - - - - - - - -Ylonen & Moffat Expires March 2, 2003 [Page 1] - -Internet-Draft SSH Authentication Protocol September 2002 - - -Table of Contents - - 1. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 3 - 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 - 3. Conventions Used in This Document . . . . . . . . . . . . . 3 - 3.1 The Authentication Protocol Framework . . . . . . . . . . . 3 - 3.1.1 Authentication Requests . . . . . . . . . . . . . . . . . . 4 - 3.1.2 Responses to Authentication Requests . . . . . . . . . . . . 5 - 3.1.3 The "none" Authentication Request . . . . . . . . . . . . . 6 - 3.1.4 Completion of User Authentication . . . . . . . . . . . . . 6 - 3.1.5 Banner Message . . . . . . . . . . . . . . . . . . . . . . . 7 - 3.2 Authentication Protocol Message Numbers . . . . . . . . . . 7 - 3.3 Public Key Authentication Method: publickey . . . . . . . . 8 - 3.4 Password Authentication Method: password . . . . . . . . . . 10 - 3.5 Host-Based Authentication: hostbased . . . . . . . . . . . . 11 - 4. Security Considerations . . . . . . . . . . . . . . . . . . 12 - Normative . . . . . . . . . . . . . . . . . . . . . . . . . 13 - Informative . . . . . . . . . . . . . . . . . . . . . . . . 13 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 14 - Intellectual Property and Copyright Statements . . . . . . . 15 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Ylonen & Moffat Expires March 2, 2003 [Page 2] - -Internet-Draft SSH Authentication Protocol September 2002 - - -1. Contributors - - The major original contributors of this document were: Tatu Ylonen, - Tero Kivinen, Timo J. Rinne, Sami Lehtinen (all of SSH Communications - Security Corp), and Markku-Juhani O. Saarinen (University of - Jyvaskyla) - - The document editor is: [email protected]. Comments on this - internet draft should be sent to the IETF SECSH working group, - details at: http://ietf.org/html.charters/secsh-charter.html - -2. Introduction - - The SSH authentication protocol is a general-purpose user - authentication protocol. It is intended to be run over the SSH - transport layer protocol [SSH-TRANS]. This protocol assumes that the - underlying protocols provide integrity and confidentiality - protection. - - This document should be read only after reading the SSH architecture - document [SSH-ARCH]. This document freely uses terminology and - notation from the architecture document without reference or further - explanation. - - The service name for this protocol is "ssh-userauth". - - When this protocol starts, it receives the session identifier from - the lower-level protocol (this is the exchange hash H from the first - key exchange). The session identifier uniquely identifies this - session and is suitable for signing in order to prove ownership of a - private key. This protocol also needs to know whether the lower-level - protocol provides confidentiality protection. - -3. Conventions Used in This Document - - The keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", - and "MAY" that appear in this document are to be interpreted as - described in [RFC2119] - - The used data types and terminology are specified in the architecture - document [SSH-ARCH] - - The architecture document also discusses the algorithm naming - conventions that MUST be used with the SSH protocols. - -3.1 The Authentication Protocol Framework - - The server drives the authentication by telling the client which - - - -Ylonen & Moffat Expires March 2, 2003 [Page 3] - -Internet-Draft SSH Authentication Protocol September 2002 - - - authentication methods can be used to continue the exchange at any - given time. The client has the freedom to try the methods listed by - the server in any order. This gives the server complete control over - the authentication process if desired, but also gives enough - flexibility for the client to use the methods it supports or that are - most convenient for the user, when multiple methods are offered by - the server. - - Authentication methods are identified by their name, as defined in - [SSH-ARCH]. The "none" method is reserved, and MUST NOT be listed as - supported. However, it MAY be sent by the client. The server MUST - always reject this request, unless the client is to be allowed in - without any authentication, in which case the server MUST accept this - request. The main purpose of sending this request is to get the list - of supported methods from the server. - - The server SHOULD have a timeout for authentication, and disconnect - if the authentication has not been accepted within the timeout - period. The RECOMMENDED timeout period is 10 minutes. Additionally, - the implementation SHOULD limit the number of failed authentication - attempts a client may perform in a single session (the RECOMMENDED - limit is 20 attempts). If the threshold is exceeded, the server - SHOULD disconnect. - -3.1.1 Authentication Requests - - All authentication requests MUST use the following message format. - Only the first few fields are defined; the remaining fields depend on - the authentication method. - - byte SSH_MSG_USERAUTH_REQUEST - string user name (in ISO-10646 UTF-8 encoding [RFC2279]) - string service name (in US-ASCII) - string method name (US-ASCII) - The rest of the packet is method-specific. - - The user name and service are repeated in every new authentication - attempt, and MAY change. The server implementation MUST carefully - check them in every message, and MUST flush any accumulated - authentication states if they change. If it is unable to flush some - authentication state, it MUST disconnect if the user or service name - changes. - - The service name specifies the service to start after authentication. - There may be several different authenticated services provided. If - the requested service is not available, the server MAY disconnect - immediately or at any later time. Sending a proper disconnect - message is RECOMMENDED. In any case, if the service does not exist, - - - -Ylonen & Moffat Expires March 2, 2003 [Page 4] - -Internet-Draft SSH Authentication Protocol September 2002 - - - authentication MUST NOT be accepted. - - If the requested user does not exist, the server MAY disconnect, or - MAY send a bogus list of acceptable authentication methods, but never - accept any. This makes it possible for the server to avoid - disclosing information on which accounts exist. In any case, if the - user does not exist, the authentication request MUST NOT be accepted. - - While there is usually little point for clients to send requests that - the server does not list as acceptable, sending such requests is not - an error, and the server SHOULD simply reject requests that it does - not recognize. - - An authentication request MAY result in a further exchange of - messages. All such messages depend on the authentication method - used, and the client MAY at any time continue with a new - SSH_MSG_USERAUTH_REQUEST message, in which case the server MUST - abandon the previous authentication attempt and continue with the new - one. - -3.1.2 Responses to Authentication Requests - - If the server rejects the authentication request, it MUST respond - with the following: - - byte SSH_MSG_USERAUTH_FAILURE - string authentications that can continue - boolean partial success - - "Authentications that can continue" is a comma-separated list of - authentication method names that may productively continue the - authentication dialog. - - It is RECOMMENDED that servers only include those methods in the list - that are actually useful. However, it is not illegal to include - methods that cannot be used to authenticate the user. - - Already successfully completed authentications SHOULD NOT be included - in the list, unless they really should be performed again for some - reason. - - "Partial success" MUST be TRUE if the authentication request to which - this is a response was successful. It MUST be FALSE if the request - was not successfully processed. - - When the server accepts authentication, it MUST respond with the - following: - - - - -Ylonen & Moffat Expires March 2, 2003 [Page 5] - -Internet-Draft SSH Authentication Protocol September 2002 - - - byte SSH_MSG_USERAUTH_SUCCESS - - Note that this is not sent after each step in a multi-method - authentication sequence, but only when the authentication is - complete. - - The client MAY send several authentication requests without waiting - for responses from previous requests. The server MUST process each - request completely and acknowledge any failed requests with a - SSH_MSG_USERAUTH_FAILURE message before processing the next request. - - A request that results in further exchange of messages will be - aborted by a second request. It is not possible to send a second - request without waiting for a response from the server, if the first - request will result in further exchange of messages. No - SSH_MSG_USERAUTH_FAILURE message will be sent for the aborted method. - - SSH_MSG_USERAUTH_SUCCESS MUST be sent only once. When - SSH_MSG_USERAUTH_SUCCESS has been sent, any further authentication - requests received after that SHOULD be silently ignored. - - Any non-authentication messages sent by the client after the request - that resulted in SSH_MSG_USERAUTH_SUCCESS being sent MUST be passed - to the service being run on top of this protocol. Such messages can - be identified by their message numbers (see Section Message Numbers - (Section 3.2)). - -3.1.3 The "none" Authentication Request - - A client may request a list of authentication methods that may - continue by using the "none" authentication method. - - If no authentication at all is needed for the user, the server MUST - return SSH_MSG_USERAUTH_SUCCESS. Otherwise, the server MUST return - SSH_MSG_USERAUTH_FAILURE and MAY return with it a list of - authentication methods that can continue. - - This method MUST NOT be listed as supported by the server. - -3.1.4 Completion of User Authentication - - Authentication is complete when the server has responded with - SSH_MSG_USERAUTH_SUCCESS; all authentication related messages - received after sending this message SHOULD be silently ignored. - - After sending SSH_MSG_USERAUTH_SUCCESS, the server starts the - requested service. - - - - -Ylonen & Moffat Expires March 2, 2003 [Page 6] - -Internet-Draft SSH Authentication Protocol September 2002 - - -3.1.5 Banner Message - - In some jurisdictions, sending a warning message before - authentication may be relevant for getting legal protection. Many - UNIX machines, for example, normally display text from `/etc/issue', - or use "tcp wrappers" or similar software to display a banner before - issuing a login prompt. - - The SSH server may send a SSH_MSG_USERAUTH_BANNER message at any time - before authentication is successful. This message contains text to - be displayed to the client user before authentication is attempted. - The format is as follows: - - byte SSH_MSG_USERAUTH_BANNER - string message (ISO-10646 UTF-8) - string language tag (as defined in [RFC3066]) - - The client SHOULD by default display the message on the screen. - However, since the message is likely to be sent for every login - attempt, and since some client software will need to open a separate - window for this warning, the client software may allow the user to - explicitly disable the display of banners from the server. The - message may consist of multiple lines. - - If the message string is displayed, control character filtering - discussed in [SSH-ARCH] SHOULD be used to avoid attacks by sending - terminal control characters. - -3.2 Authentication Protocol Message Numbers - - All message numbers used by this authentication protocol are in the - range from 50 to 79, which is part of the range reserved for - protocols running on top of the SSH transport layer protocol. - - Message numbers of 80 and higher are reserved for protocols running - after this authentication protocol, so receiving one of them before - authentication is complete is an error, to which the server MUST - respond by disconnecting (preferably with a proper disconnect message - sent first to ease troubleshooting). - - After successful authentication, such messages are passed to the - higher-level service. - - These are the general authentication message codes: - - #define SSH_MSG_USERAUTH_REQUEST 50 - #define SSH_MSG_USERAUTH_FAILURE 51 - #define SSH_MSG_USERAUTH_SUCCESS 52 - - - -Ylonen & Moffat Expires March 2, 2003 [Page 7] - -Internet-Draft SSH Authentication Protocol September 2002 - - - #define SSH_MSG_USERAUTH_BANNER 53 - - In addition to the above, there is a range of message numbers - (60..79) reserved for method-specific messages. These messages are - only sent by the server (client sends only SSH_MSG_USERAUTH_REQUEST - messages). Different authentication methods reuse the same message - numbers. - -3.3 Public Key Authentication Method: publickey - - The only REQUIRED authentication method is public key authentication. - All implementations MUST support this method; however, not all users - need to have public keys, and most local policies are not likely to - require public key authentication for all users in the near future. - - With this method, the possession of a private key serves as - authentication. This method works by sending a signature created - with a private key of the user. The server MUST check that the key - is a valid authenticator for the user, and MUST check that the - signature is valid. If both hold, the authentication request MUST be - accepted; otherwise it MUST be rejected. (Note that the server MAY - require additional authentications after successful authentication.) - - Private keys are often stored in an encrypted form at the client - host, and the user must supply a passphrase before the signature can - be generated. Even if they are not, the signing operation involves - some expensive computation. To avoid unnecessary processing and user - interaction, the following message is provided for querying whether - authentication using the key would be acceptable. - - byte SSH_MSG_USERAUTH_REQUEST - string user name - string service - string "publickey" - boolean FALSE - string public key algorithm name - string public key blob - - Public key algorithms are defined in the transport layer - specification [SSH-TRANS]. The public key blob may contain - certificates. - - Any public key algorithm may be offered for use in authentication. - In particular, the list is not constrained by what was negotiated - during key exchange. If the server does not support some algorithm, - it MUST simply reject the request. - - The server MUST respond to this message with either - - - -Ylonen & Moffat Expires March 2, 2003 [Page 8] - -Internet-Draft SSH Authentication Protocol September 2002 - - - SSH_MSG_USERAUTH_FAILURE or with the following: - - byte SSH_MSG_USERAUTH_PK_OK - string public key algorithm name from the request - string public key blob from the request - - To perform actual authentication, the client MAY then send a - signature generated using the private key. The client MAY send the - signature directly without first verifying whether the key is - acceptable. The signature is sent using the following packet: - - byte SSH_MSG_USERAUTH_REQUEST - string user name - string service - string "publickey" - boolean TRUE - string public key algorithm name - string public key to be used for authentication - string signature - - Signature is a signature by the corresponding private key over the - following data, in the following order: - - string session identifier - byte SSH_MSG_USERAUTH_REQUEST - string user name - string service - string "publickey" - boolean TRUE - string public key algorithm name - string public key to be used for authentication - - When the server receives this message, it MUST check whether the - supplied key is acceptable for authentication, and if so, it MUST - check whether the signature is correct. - - If both checks succeed, this method is successful. Note that the - server may require additional authentications. The server MUST - respond with SSH_MSG_USERAUTH_SUCCESS (if no more authentications are - needed), or SSH_MSG_USERAUTH_FAILURE (if the request failed, or more - authentications are needed). - - The following method-specific message numbers are used by the - publickey authentication method. - - /* Key-based */ - #define SSH_MSG_USERAUTH_PK_OK 60 - - - - -Ylonen & Moffat Expires March 2, 2003 [Page 9] - -Internet-Draft SSH Authentication Protocol September 2002 - - -3.4 Password Authentication Method: password - - Password authentication uses the following packets. Note that a - server MAY request the user to change the password. All - implementations SHOULD support password authentication. - - byte SSH_MSG_USERAUTH_REQUEST - string user name - string service - string "password" - boolean FALSE - string plaintext password (ISO-10646 UTF-8) - - Note that the password is encoded in ISO-10646 UTF-8. It is up to - the server how it interprets the password and validates it against - the password database. However, if the client reads the password in - some other encoding (e.g., ISO 8859-1 (ISO Latin1)), it MUST convert - the password to ISO-10646 UTF-8 before transmitting, and the server - MUST convert the password to the encoding used on that system for - passwords. - - Note that even though the cleartext password is transmitted in the - packet, the entire packet is encrypted by the transport layer. Both - the server and the client should check whether the underlying - transport layer provides confidentiality (i.e., if encryption is - being used). If no confidentiality is provided (none cipher), - password authentication SHOULD be disabled. If there is no - confidentiality or no MAC, password change SHOULD be disabled. - - Normally, the server responds to this message with success or - failure. However, if the password has expired the server SHOULD - indicate this by responding with SSH_MSG_USERAUTH_PASSWD_CHANGEREQ. - In anycase the server MUST NOT allow an expired password to be used - for authentication. - - byte SSH_MSG_USERAUTH_PASSWD_CHANGEREQ - string prompt (ISO-10646 UTF-8) - string language tag (as defined in [RFC3066]) - - In this case, the client MAY continue with a different authentication - method, or request a new password from the user and retry password - authentication using the following message. The client MAY also send - this message instead of the normal password authentication request - without the server asking for it. - - byte SSH_MSG_USERAUTH_REQUEST - string user name - string service - - - -Ylonen & Moffat Expires March 2, 2003 [Page 10] - -Internet-Draft SSH Authentication Protocol September 2002 - - - string "password" - boolean TRUE - string plaintext old password (ISO-10646 UTF-8) - string plaintext new password (ISO-10646 UTF-8) - - The server must reply to request message with - SSH_MSG_USERAUTH_SUCCESS, SSH_MSG_USERAUTH_FAILURE, or another - SSH_MSG_USERAUTH_PASSWD_CHANGEREQ. The meaning of these is as - follows: - - SSH_MSG_USERAUTH_SUCCESS The password has been changed, and - authentication has been successfully completed. - - SSH_MSG_USERAUTH_FAILURE with partial success The password has - been changed, but more authentications are needed. - - SSH_MSG_USERAUTH_FAILURE without partial success The password has - not been changed. Either password changing was not supported, or - the old password was bad. Note that if the server has already - sent SSH_MSG_USERAUTH_PASSWD_CHANGEREQ, we know that it supports - changing the password. - - SSH_MSG_USERAUTH_CHANGEREQ The password was not changed because - the new password was not acceptable (e.g. too easy to guess). - - The following method-specific message numbers are used by the - password authentication method. - - #define SSH_MSG_USERAUTH_PASSWD_CHANGEREQ 60 - - -3.5 Host-Based Authentication: hostbased - - Some sites wish to allow authentication based on the host where the - user is coming from, and the user name on the remote host. While - this form of authentication is not suitable for high-security sites, - it can be very convenient in many environments. This form of - authentication is OPTIONAL. When used, special care SHOULD be taken - to prevent a regular user from obtaining the private host key. - - The client requests this form of authentication by sending the - following message. It is similar to the UNIX "rhosts" and - "hosts.equiv" styles of authentication, except that the identity of - the client host is checked more rigorously. - - This method works by having the client send a signature created with - the private key of the client host, which the server checks with that - host's public key. Once the client host's identity is established, - - - -Ylonen & Moffat Expires March 2, 2003 [Page 11] - -Internet-Draft SSH Authentication Protocol September 2002 - - - authorization (but no further authentication) is performed based on - the user names on the server and the client, and the client host - name. - - byte SSH_MSG_USERAUTH_REQUEST - string user name - string service - string "hostbased" - string public key algorithm for host key - string public host key and certificates for client host - string client host name (FQDN; US-ASCII) - string user name on the client host (ISO-10646 UTF-8) - string signature - - Public key algorithm names for use in "public key algorithm for host - key" are defined in the transport layer specification. The "public - host key for client host" may include certificates. - - Signature is a signature with the private host key of the following - data, in this order: - - string session identifier - byte SSH_MSG_USERAUTH_REQUEST - string user name - string service - string "hostbased" - string public key algorithm for host key - string public host key and certificates for client host - string client host name (FQDN; US-ASCII) - string user name on the client host(ISO-10646 UTF-8) - - The server MUST verify that the host key actually belongs to the - client host named in the message, that the given user on that host is - allowed to log in, and that the signature is a valid signature on the - appropriate value by the given host key. The server MAY ignore the - client user name, if it wants to authenticate only the client host. - - It is RECOMMENDED that whenever possible, the server perform - additional checks to verify that the network address obtained from - the (untrusted) network matches the given client host name. This - makes exploiting compromised host keys more difficult. Note that - this may require special handling for connections coming through a - firewall. - -4. Security Considerations - - The purpose of this protocol is to perform client user - authentication. It assumed that this runs over a secure transport - - - -Ylonen & Moffat Expires March 2, 2003 [Page 12] - -Internet-Draft SSH Authentication Protocol September 2002 - - - layer protocol, which has already authenticated the server machine, - established an encrypted communications channel, and computed a - unique session identifier for this session. The transport layer - provides forward secrecy for password authentication and other - methods that rely on secret data. - - Full security considerations for this protocol are provided in - Section 8 of [SSH-ARCH] - -Normative - - [SSH-ARCH] - Ylonen, T., "SSH Protocol Architecture", I-D - draft-ietf-architecture-15.txt, Oct 2003. - - [SSH-TRANS] - Ylonen, T., "SSH Transport Layer Protocol", I-D - draft-ietf-transport-17.txt, Oct 2003. - - [SSH-USERAUTH] - Ylonen, T., "SSH Authentication Protocol", I-D - draft-ietf-userauth-18.txt, Oct 2003. - - [SSH-CONNECT] - Ylonen, T., "SSH Connection Protocol", I-D - draft-ietf-connect-18.txt, Oct 2003. - - [SSH-NUMBERS] - Lehtinen, S. and D. Moffat, "SSH Protocol Assigned - Numbers", I-D draft-ietf-secsh-assignednumbers-05.txt, Oct - 2003. - - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - -Informative - - [RFC3066] Alvestrand, H., "Tags for the Identification of - Languages", BCP 47, RFC 3066, January 2001. - - [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO - 10646", RFC 2279, January 1998. - - - - - - - - - -Ylonen & Moffat Expires March 2, 2003 [Page 13] - -Internet-Draft SSH Authentication Protocol September 2002 - - -Authors' Addresses - - Tatu Ylonen - SSH Communications Security Corp - Fredrikinkatu 42 - HELSINKI FIN-00100 - Finland - - EMail: [email protected] - - - Darren J. Moffat (editor) - Sun Microsystems, Inc - 17 Network Circle - Menlo Park 95025 - USA - - EMail: [email protected] - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Ylonen & Moffat Expires March 2, 2003 [Page 14] - -Internet-Draft SSH Authentication Protocol September 2002 - - -Intellectual Property Statement - - The IETF takes no position regarding the validity or scope of any - intellectual property 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; neither does it represent that it - has made any effort to identify any such rights. Information on the - IETF's procedures with respect to rights in standards-track and - standards-related documentation can be found in BCP-11. Copies of - claims of rights made available for publication 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 implementors or users of this specification can - be obtained from the IETF Secretariat. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights which may cover technology that may be required to practice - this standard. Please address the information to the IETF Executive - Director. - - The IETF has been notified of intellectual property rights claimed in - regard to some or all of the specification contained in this - document. For more information consult the online list of claimed - rights. - - -Full Copyright Statement - - Copyright (C) The Internet Society (2002). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assignees. - - - -Ylonen & Moffat Expires March 2, 2003 [Page 15] - -Internet-Draft SSH Authentication Protocol September 2002 - - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS 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. - - -Acknowledgment - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Ylonen & Moffat Expires March 2, 2003 [Page 16]
\ No newline at end of file diff --git a/lib/ssh/src/ssh.erl b/lib/ssh/src/ssh.erl index 5bde184070..54f94acbdc 100644 --- a/lib/ssh/src/ssh.erl +++ b/lib/ssh/src/ssh.erl @@ -235,10 +235,27 @@ start_daemon(Host, Port, Options, Inet) -> {error, _Reason} = Error -> Error; {SocketOptions, SshOptions}-> - do_start_daemon(Host, Port,[{role, server} |SshOptions] , [Inet | SocketOptions]) + try + do_start_daemon(Host, Port,[{role, server} |SshOptions] , [Inet | SocketOptions]) + catch + throw:bad_fd -> {error,bad_fd}; + _C:_E -> {error,{cannot_start_daemon,_C,_E}} + end end. -do_start_daemon(Host, Port, Options, SocketOptions) -> +do_start_daemon(Host0, Port0, Options, SocketOptions) -> + {Host,Port} = try + case proplists:get_value(fd, SocketOptions) of + undefined -> + {Host0,Port0}; + Fd when Port0==0 -> + find_hostport(Fd); + _ -> + {Host0,Port0} + end + catch + _:_ -> throw(bad_fd) + end, Profile = proplists:get_value(profile, Options, ?DEFAULT_PROFILE), case ssh_system_sup:system_supervisor(Host, Port, Profile) of undefined -> @@ -272,6 +289,15 @@ do_start_daemon(Host, Port, Options, SocketOptions) -> end end. +find_hostport(Fd) -> + %% Using internal functions inet:open/8 and inet:close/0. + %% Don't try this at home unless you know what you are doing! + {ok,S} = inet:open(Fd, {0,0,0,0}, 0, [], tcp, inet, stream, inet_tcp), + {ok, HostPort} = inet:sockname(S), + ok = inet:close(S), + HostPort. + + handle_options(Opts) -> try handle_option(algs_compatibility(proplists:unfold(Opts)), [], []) of {Inet, Ssh} -> @@ -282,32 +308,27 @@ handle_options(Opts) -> end. -algs_compatibility(Os) -> +algs_compatibility(Os0) -> %% Take care of old options 'public_key_alg' and 'pref_public_key_algs' - comp_pk(proplists:get_value(preferred_algorithms,Os), - proplists:get_value(pref_public_key_algs,Os), - proplists:get_value(public_key_alg, Os), - [{K,V} || {K,V} <- Os, - K =/= public_key_alg, - K =/= pref_public_key_algs] - ). - -comp_pk(undefined, undefined, undefined, Os) -> Os; -comp_pk( PrefAlgs, _, _, Os) when PrefAlgs =/= undefined -> Os; - -comp_pk(undefined, undefined, ssh_dsa, Os) -> comp_pk(undefined, undefined, 'ssh-dss', Os); -comp_pk(undefined, undefined, ssh_rsa, Os) -> comp_pk(undefined, undefined, 'ssh-rsa', Os); -comp_pk(undefined, undefined, PK, Os) -> - PKs = [PK | ssh_transport:supported_algorithms(public_key)--[PK]], - [{preferred_algorithms, [{public_key,PKs}] } | Os]; - -comp_pk(undefined, PrefPKs, _, Os) when PrefPKs =/= undefined -> - PKs = [case PK of - ssh_dsa -> 'ssh-dss'; - ssh_rsa -> 'ssh-rsa'; - _ -> PK - end || PK <- PrefPKs], - [{preferred_algorithms, [{public_key,PKs}]} | Os]. + case proplists:get_value(public_key_alg, Os0) of + undefined -> + Os0; + A when is_atom(A) -> + %% Skip public_key_alg if pref_public_key_algs is defined: + Os = lists:keydelete(public_key_alg, 1, Os0), + case proplists:get_value(pref_public_key_algs,Os) of + undefined when A == 'ssh-rsa' ; A==ssh_rsa -> + [{pref_public_key_algs,['ssh-rsa','ssh-dss']} | Os]; + undefined when A == 'ssh-dss' ; A==ssh_dsa -> + [{pref_public_key_algs,['ssh-dss','ssh-rsa']} | Os]; + undefined -> + throw({error, {eoptions, {public_key_alg,A} }}); + _ -> + Os + end; + V -> + throw({error, {eoptions, {public_key_alg,V} }}) + end. handle_option([], SocketOptions, SshOptions) -> @@ -336,8 +357,12 @@ handle_option([{user_passwords, _} = Opt | Rest], SocketOptions, SshOptions) -> handle_option(Rest, SocketOptions, [handle_ssh_option(Opt) | SshOptions]); handle_option([{pwdfun, _} = Opt | Rest], SocketOptions, SshOptions) -> handle_option(Rest, SocketOptions, [handle_ssh_option(Opt) | SshOptions]); -handle_option([{key_cb, _} = Opt | Rest], SocketOptions, SshOptions) -> - handle_option(Rest, SocketOptions, [handle_ssh_option(Opt) | SshOptions]); +handle_option([{key_cb, {Module, Options}} | Rest], SocketOptions, SshOptions) -> + handle_option(Rest, SocketOptions, [handle_ssh_option({key_cb, Module}), + handle_ssh_priv_option({key_cb_private, Options}) | + SshOptions]); +handle_option([{key_cb, Module} | Rest], SocketOptions, SshOptions) -> + handle_option([{key_cb, {Module, []}} | Rest], SocketOptions, SshOptions); handle_option([{keyboard_interact_fun, _} = Opt | Rest], SocketOptions, SshOptions) -> handle_option(Rest, SocketOptions, [handle_ssh_option(Opt) | SshOptions]); %%Backwards compatibility @@ -374,6 +399,8 @@ handle_option([{auth_methods, _} = Opt | Rest], SocketOptions, SshOptions) -> handle_option(Rest, SocketOptions, [handle_ssh_option(Opt) | SshOptions]); handle_option([{auth_method_kb_interactive_data, _} = Opt | Rest], SocketOptions, SshOptions) -> handle_option(Rest, SocketOptions, [handle_ssh_option(Opt) | SshOptions]); +handle_option([{pref_public_key_algs, _} = Opt | Rest], SocketOptions, SshOptions) -> + handle_option(Rest, SocketOptions, [handle_ssh_option(Opt) | SshOptions]); handle_option([{preferred_algorithms,_} = Opt | Rest], SocketOptions, SshOptions) -> handle_option(Rest, SocketOptions, [handle_ssh_option(Opt) | SshOptions]); handle_option([{dh_gex_groups,_} = Opt | Rest], SocketOptions, SshOptions) -> @@ -485,6 +512,13 @@ handle_ssh_option({dh_gex_limits,{Min,I,Max}} = Opt) when is_integer(Min), Min>0 is_integer(Max), Max>=I -> %% Client Opt; +handle_ssh_option({pref_public_key_algs, Value} = Opt) when is_list(Value), length(Value) >= 1 -> + case handle_user_pref_pubkey_algs(Value, []) of + {true, NewOpts} -> + {pref_public_key_algs, NewOpts}; + _ -> + throw({error, {eoptions, Opt}}) + end; handle_ssh_option({connect_timeout, Value} = Opt) when is_integer(Value); Value == infinity -> Opt; handle_ssh_option({max_sessions, Value} = Opt) when is_integer(Value), Value>0 -> @@ -511,6 +545,9 @@ handle_ssh_option({pwdfun, Value} = Opt) when is_function(Value,4) -> Opt; handle_ssh_option({key_cb, Value} = Opt) when is_atom(Value) -> Opt; +handle_ssh_option({key_cb, {CallbackMod, CallbackOptions}} = Opt) when is_atom(CallbackMod), + is_list(CallbackOptions) -> + Opt; handle_ssh_option({keyboard_interact_fun, Value} = Opt) when is_function(Value,3) -> Opt; handle_ssh_option({compression, Value} = Opt) when is_atom(Value) -> @@ -577,6 +614,9 @@ handle_ssh_option({profile, Value} = Opt) when is_atom(Value) -> handle_ssh_option(Opt) -> throw({error, {eoptions, Opt}}). +handle_ssh_priv_option({key_cb_private, Value} = Opt) when is_list(Value) -> + Opt. + handle_inet_option({active, _} = Opt) -> throw({error, {{eoptions, Opt}, "SSH has built in flow control, " "and active is handled internally, user is not allowed" @@ -737,3 +777,16 @@ read_moduli_file(D, I, Acc) -> end end. +handle_user_pref_pubkey_algs([], Acc) -> + {true, lists:reverse(Acc)}; +handle_user_pref_pubkey_algs([H|T], Acc) -> + case lists:member(H, ?SUPPORTED_USER_KEYS) of + true -> + handle_user_pref_pubkey_algs(T, [H| Acc]); + + false when H==ssh_dsa -> handle_user_pref_pubkey_algs(T, ['ssh-dss'| Acc]); + false when H==ssh_rsa -> handle_user_pref_pubkey_algs(T, ['ssh-rsa'| Acc]); + + false -> + false + end. diff --git a/lib/ssh/src/ssh.hrl b/lib/ssh/src/ssh.hrl index 4ad936f742..f88098819d 100644 --- a/lib/ssh/src/ssh.hrl +++ b/lib/ssh/src/ssh.hrl @@ -29,11 +29,13 @@ -define(SSH_DEFAULT_PORT, 22). -define(SSH_MAX_PACKET_SIZE, (256*1024)). --define(SSH_LENGHT_INDICATOR_SIZE, 4). -define(REKEY_TIMOUT, 3600000). -define(REKEY_DATA_TIMOUT, 60000). -define(DEFAULT_PROFILE, default). +-define(SUPPORTED_AUTH_METHODS, "publickey,keyboard-interactive,password"). +-define(SUPPORTED_USER_KEYS, ['ssh-rsa','ssh-dss','ecdsa-sha2-nistp256','ecdsa-sha2-nistp384','ecdsa-sha2-nistp521']). + -define(FALSE, 0). -define(TRUE, 1). %% basic binary constructors diff --git a/lib/ssh/src/ssh_acceptor.erl b/lib/ssh/src/ssh_acceptor.erl index c5ad1d7b6c..d94dedf1bf 100644 --- a/lib/ssh/src/ssh_acceptor.erl +++ b/lib/ssh/src/ssh_acceptor.erl @@ -56,7 +56,12 @@ acceptor_init(Parent, Port, Address, SockOpts, Opts, AcceptTimeout) -> error end. -do_socket_listen(Callback, Port, Opts) -> +do_socket_listen(Callback, Port0, Opts) -> + Port = + case proplists:get_value(fd, Opts) of + undefined -> Port0; + _ -> 0 + end, case Callback:listen(Port, Opts) of {error, nxdomain} -> Callback:listen(Port, lists:delete(inet6, Opts)); diff --git a/lib/ssh/src/ssh_auth.erl b/lib/ssh/src/ssh_auth.erl index 4967a2e4cd..fdbb5c152a 100644 --- a/lib/ssh/src/ssh_auth.erl +++ b/lib/ssh/src/ssh_auth.erl @@ -118,11 +118,16 @@ init_userauth_request_msg(#ssh{opts = Opts} = Ssh) -> service = "ssh-connection", method = "none", data = <<>>}, + Algs0 = proplists:get_value(pref_public_key_algs, Opts, ?SUPPORTED_USER_KEYS), + %% The following line is not strictly correct. The call returns the + %% supported HOST key types while we are interested in USER keys. However, + %% they "happens" to be the same (for now). This could change.... + %% There is no danger as long as the set of user keys is a subset of the set + %% of host keys. + CryptoSupported = ssh_transport:supported_algorithms(public_key), + Algs = [A || A <- Algs0, + lists:member(A, CryptoSupported)], - - Algs = proplists:get_value(public_key, - proplists:get_value(preferred_algorithms, Opts, []), - ssh_transport:default_algorithms(public_key)), Prefs = method_preference(Algs), ssh_transport:ssh_packet(Msg, Ssh#ssh{user = User, userauth_preference = Prefs, diff --git a/lib/ssh/src/ssh_auth.hrl b/lib/ssh/src/ssh_auth.hrl index 5197a42fa4..449bc4fa45 100644 --- a/lib/ssh/src/ssh_auth.hrl +++ b/lib/ssh/src/ssh_auth.hrl @@ -22,7 +22,6 @@ %%% Description: Ssh User Authentication Protocol --define(SUPPORTED_AUTH_METHODS, "publickey,keyboard-interactive,password"). -define(SSH_MSG_USERAUTH_REQUEST, 50). -define(SSH_MSG_USERAUTH_FAILURE, 51). diff --git a/lib/ssh/src/ssh_connect.hrl b/lib/ssh/src/ssh_connect.hrl index 6db89c5d80..9f9f3de8fa 100644 --- a/lib/ssh/src/ssh_connect.hrl +++ b/lib/ssh/src/ssh_connect.hrl @@ -248,6 +248,9 @@ local_id, %% local channel id recv_window_size, + recv_window_pending = 0, %% Sum of window size updates that has not + %% yet been sent. This limits the number + %% of sent update msgs. recv_packet_size, recv_close = false, diff --git a/lib/ssh/src/ssh_connection_handler.erl b/lib/ssh/src/ssh_connection_handler.erl index 8448218d91..516a09bf6a 100644 --- a/lib/ssh/src/ssh_connection_handler.erl +++ b/lib/ssh/src/ssh_connection_handler.erl @@ -433,6 +433,12 @@ key_exchange(#ssh_msg_kex_dh_gex_request{} = Msg, send_msg(GexGroup, State), {next_state, key_exchange_dh_gex_init, next_packet(State#state{ssh_params = Ssh})}; +key_exchange(#ssh_msg_kex_dh_gex_request_old{} = Msg, + #state{ssh_params = #ssh{role = server} = Ssh0} = State) -> + {ok, GexGroup, Ssh} = ssh_transport:handle_kex_dh_gex_request(Msg, Ssh0), + send_msg(GexGroup, State), + {next_state, key_exchange_dh_gex_init, next_packet(State#state{ssh_params = Ssh})}; + key_exchange(#ssh_msg_kex_dh_gex_group{} = Msg, #state{ssh_params = #ssh{role = client} = Ssh0} = State) -> {ok, KexGexInit, Ssh} = ssh_transport:handle_kex_dh_gex_group(Msg, Ssh0), @@ -731,13 +737,28 @@ handle_event({adjust_window, ChannelId, Bytes}, StateName, #connection{channel_cache = Cache}} = State0) -> State = case ssh_channel:cache_lookup(Cache, ChannelId) of - #channel{recv_window_size = WinSize, remote_id = Id} = Channel -> - ssh_channel:cache_update(Cache, Channel#channel{recv_window_size = - WinSize + Bytes}), - Msg = ssh_connection:channel_adjust_window_msg(Id, Bytes), + #channel{recv_window_size = WinSize, + recv_window_pending = Pending, + recv_packet_size = PktSize} = Channel + when (WinSize-Bytes) >= 2*PktSize -> + %% The peer can send at least two more *full* packet, no hurry. + ssh_channel:cache_update(Cache, + Channel#channel{recv_window_pending = Pending + Bytes}), + State0; + + #channel{recv_window_size = WinSize, + recv_window_pending = Pending, + remote_id = Id} = Channel -> + %% Now we have to update the window - we can't receive so many more pkts + ssh_channel:cache_update(Cache, + Channel#channel{recv_window_size = + WinSize + Bytes + Pending, + recv_window_pending = 0}), + Msg = ssh_connection:channel_adjust_window_msg(Id, Bytes + Pending), send_replies([{connection_reply, Msg}], State0); - undefined -> - State0 + + undefined -> + State0 end, {next_state, StateName, next_packet(State)}; @@ -970,57 +991,39 @@ handle_info({Protocol, Socket, Info}, hello, transport_protocol = Protocol} = State) -> event({info_line, Info}, hello, State); -handle_info({Protocol, Socket, Data}, Statename, +handle_info({Protocol, Socket, Data}, StateName, #state{socket = Socket, transport_protocol = Protocol, - ssh_params = #ssh{decrypt_block_size = BlockSize, - recv_mac_size = MacSize} = Ssh0, - decoded_data_buffer = <<>>, - encoded_data_buffer = EncData0} = State0) -> - - %% Implementations SHOULD decrypt the length after receiving the - %% first 8 (or cipher block size, whichever is larger) bytes of a - %% packet. (RFC 4253: Section 6 - Binary Packet Protocol) - case size(EncData0) + size(Data) >= erlang:max(8, BlockSize) of - true -> - {Ssh, SshPacketLen, DecData, EncData} = - - ssh_transport:decrypt_first_block(<<EncData0/binary, - Data/binary>>, Ssh0), - case SshPacketLen > ?SSH_MAX_PACKET_SIZE of - true -> - DisconnectMsg = - #ssh_msg_disconnect{code = - ?SSH_DISCONNECT_PROTOCOL_ERROR, - description = "Bad packet length " - ++ integer_to_list(SshPacketLen), - language = "en"}, - handle_disconnect(DisconnectMsg, State0); - false -> - RemainingSshPacketLen = - (SshPacketLen + ?SSH_LENGHT_INDICATOR_SIZE) - - BlockSize + MacSize, - State = State0#state{ssh_params = Ssh}, - handle_ssh_packet_data(RemainingSshPacketLen, - DecData, EncData, Statename, - State) - end; - false -> - {next_state, Statename, - next_packet(State0#state{encoded_data_buffer = - <<EncData0/binary, Data/binary>>})} + ssh_params = Ssh0, + decoded_data_buffer = DecData0, + encoded_data_buffer = EncData0, + undecoded_packet_length = RemainingSshPacketLen0} = State0) -> + Encoded = <<EncData0/binary, Data/binary>>, + case ssh_transport:handle_packet_part(DecData0, Encoded, RemainingSshPacketLen0, Ssh0) of + {get_more, DecBytes, EncDataRest, RemainingSshPacketLen, Ssh1} -> + {next_state, StateName, + next_packet(State0#state{encoded_data_buffer = EncDataRest, + decoded_data_buffer = DecBytes, + undecoded_packet_length = RemainingSshPacketLen, + ssh_params = Ssh1})}; + {decoded, MsgBytes, EncDataRest, Ssh1} -> + generate_event(MsgBytes, StateName, + State0#state{ssh_params = Ssh1, + %% Important to be set for + %% next_packet +%%% FIXME: the following three seem to always be set in generate_event! + decoded_data_buffer = <<>>, + undecoded_packet_length = undefined, + encoded_data_buffer = EncDataRest}, + EncDataRest); + {bad_mac, Ssh1} -> + DisconnectMsg = + #ssh_msg_disconnect{code = ?SSH_DISCONNECT_PROTOCOL_ERROR, + description = "Bad mac", + language = ""}, + handle_disconnect(DisconnectMsg, State0#state{ssh_params=Ssh1}) end; - -handle_info({Protocol, Socket, Data}, Statename, - #state{socket = Socket, - transport_protocol = Protocol, - decoded_data_buffer = DecData, - encoded_data_buffer = EncData, - undecoded_packet_length = Len} = - State) when is_integer(Len) -> - handle_ssh_packet_data(Len, DecData, <<EncData/binary, Data/binary>>, - Statename, State); - + handle_info({CloseTag, _Socket}, _StateName, #state{transport_close_tag = CloseTag, ssh_params = #ssh{role = _Role, opts = _Opts}} = State) -> @@ -1631,57 +1634,6 @@ after_new_keys_events({connection_reply, _Data} = Reply, {StateName, State}) -> NewState = send_replies([Reply], State), {next_state, StateName, NewState}. -handle_ssh_packet_data(RemainingSshPacketLen, DecData, EncData, StateName, - State) -> - EncSize = size(EncData), - case RemainingSshPacketLen > EncSize of - true -> - {next_state, StateName, - next_packet(State#state{decoded_data_buffer = DecData, - encoded_data_buffer = EncData, - undecoded_packet_length = - RemainingSshPacketLen})}; - false -> - handle_ssh_packet(RemainingSshPacketLen, StateName, - State#state{decoded_data_buffer = DecData, - encoded_data_buffer = EncData}) - - end. - -handle_ssh_packet(Length, StateName, #state{decoded_data_buffer = DecData0, - encoded_data_buffer = EncData0, - ssh_params = Ssh0, - transport_protocol = _Protocol, - socket = _Socket} = State0) -> - try - {Ssh1, DecData, EncData, Mac} = - ssh_transport:unpack(EncData0, Length, Ssh0), - SshPacket = <<DecData0/binary, DecData/binary>>, - case ssh_transport:is_valid_mac(Mac, SshPacket, Ssh1) of - true -> - PacketData = ssh_transport:msg_data(SshPacket), - {Ssh1, Msg} = ssh_transport:decompress(Ssh1, PacketData), - generate_event(Msg, StateName, - State0#state{ssh_params = Ssh1, - %% Important to be set for - %% next_packet - decoded_data_buffer = <<>>}, - EncData); - false -> - DisconnectMsg = - #ssh_msg_disconnect{code = ?SSH_DISCONNECT_PROTOCOL_ERROR, - description = "Bad mac", - language = "en"}, - handle_disconnect(DisconnectMsg, State0) - end - catch _:_ -> - Disconnect = - #ssh_msg_disconnect{code = ?SSH_DISCONNECT_PROTOCOL_ERROR, - description = "Bad input", - language = "en"}, - handle_disconnect(Disconnect, State0) - end. - handle_disconnect(DisconnectMsg, State) -> handle_disconnect(own, DisconnectMsg, State). diff --git a/lib/ssh/src/ssh_file.erl b/lib/ssh/src/ssh_file.erl index 2f16a31cba..3e066c453d 100644 --- a/lib/ssh/src/ssh_file.erl +++ b/lib/ssh/src/ssh_file.erl @@ -336,8 +336,18 @@ is_auth_key(Key, Key) -> is_auth_key(_,_) -> false. -default_user_dir()-> - {ok,[[Home|_]]} = init:get_argument(home), + +default_user_dir() -> + try + default_user_dir(os:getenv("HOME")) + catch + _:_ -> + default_user_dir(init:get_argument(home)) + end. + +default_user_dir({ok,[[Home|_]]}) -> + default_user_dir(Home); +default_user_dir(Home) when is_list(Home) -> UserDir = filename:join(Home, ".ssh"), ok = filelib:ensure_dir(filename:join(UserDir, "dummy")), {ok,Info} = file:read_file_info(UserDir), diff --git a/lib/ssh/src/ssh_sftpd.erl b/lib/ssh/src/ssh_sftpd.erl index a6549f1c73..819cba697e 100644 --- a/lib/ssh/src/ssh_sftpd.erl +++ b/lib/ssh/src/ssh_sftpd.erl @@ -30,6 +30,7 @@ -include("ssh.hrl"). -include("ssh_xfer.hrl"). +-include("ssh_connect.hrl"). %% For ?DEFAULT_PACKET_SIZE and ?DEFAULT_WINDOW_SIZE %%-------------------------------------------------------------------- %% External exports @@ -47,6 +48,7 @@ file_handler, % atom() - callback module file_state, % state for the file callback module max_files, % integer >= 0 max no files sent during READDIR + options, % from the subsystem declaration handles % list of open handles %% handle is either {<int>, directory, {Path, unread|eof}} or %% {<int>, file, {Path, IoDevice}} @@ -121,6 +123,7 @@ init(Options) -> MaxLength = proplists:get_value(max_files, Options, 0), Vsn = proplists:get_value(sftpd_vsn, Options, 5), {ok, State#state{cwd = CWD, root = Root, max_files = MaxLength, + options = Options, handles = [], pending = <<>>, xf = #ssh_xfer{vsn = Vsn, ext = []}}}. @@ -164,7 +167,9 @@ handle_ssh_msg({ssh_cm, _, {exit_status, ChannelId, Status}}, State) -> %% Description: Handles other messages %%-------------------------------------------------------------------- handle_msg({ssh_channel_up, ChannelId, ConnectionManager}, - #state{xf =Xf} = State) -> + #state{xf = Xf, + options = Options} = State) -> + maybe_increase_recv_window(ConnectionManager, ChannelId, Options), {ok, State#state{xf = Xf#ssh_xfer{cm = ConnectionManager, channel = ChannelId}}}. @@ -934,3 +939,18 @@ rename(Path, Path2, ReqId, State0) -> {Status, FS1} = FileMod:rename(Path, Path2, FS0), State1 = State0#state{file_state = FS1}, send_status(Status, ReqId, State1). + + +maybe_increase_recv_window(ConnectionManager, ChannelId, Options) -> + WantedRecvWindowSize = + proplists:get_value(recv_window_size, Options, 1000000), + NumPkts = WantedRecvWindowSize div ?DEFAULT_PACKET_SIZE, + Increment = NumPkts*?DEFAULT_PACKET_SIZE - ?DEFAULT_WINDOW_SIZE, + + if + Increment > 0 -> + ssh_connection:adjust_window(ConnectionManager, ChannelId, + Increment); + Increment =< 0 -> + do_nothing + end. diff --git a/lib/ssh/src/ssh_transport.erl b/lib/ssh/src/ssh_transport.erl index 0c999b96cc..67a0d29bb8 100644 --- a/lib/ssh/src/ssh_transport.erl +++ b/lib/ssh/src/ssh_transport.erl @@ -31,10 +31,10 @@ -include("ssh.hrl"). -export([versions/2, hello_version_msg/1]). --export([next_seqnum/1, decrypt_first_block/2, decrypt_blocks/3, +-export([next_seqnum/1, supported_algorithms/0, supported_algorithms/1, default_algorithms/0, default_algorithms/1, - is_valid_mac/3, + handle_packet_part/4, handle_hello_version/1, key_exchange_init_msg/1, key_init/3, new_keys_message/1, @@ -45,9 +45,13 @@ handle_kex_ecdh_init/2, handle_kex_ecdh_reply/2, extract_public_key/1, - unpack/3, decompress/2, ssh_packet/2, pack/2, pack/3, msg_data/1, + ssh_packet/2, pack/2, sign/3, verify/4]). +%%% For test suites +-export([pack/3]). +-export([decompress/2, decrypt_blocks/3, is_valid_mac/3 ]). % FIXME: remove + %%%---------------------------------------------------------------------------- %%% %%% There is a difference between supported and default algorithms. The @@ -66,10 +70,15 @@ default_algorithms() -> [{K,default_algorithms(K)} || K <- algo_classes()]. algo_classes() -> [kex, public_key, cipher, mac, compression]. -%% default_algorithms(kex) -> % Example of how to disable an algorithm -%% supported_algorithms(kex, ['ecdh-sha2-nistp521']); + +default_algorithms(cipher) -> + supported_algorithms(cipher, same(['AEAD_AES_128_GCM', + 'AEAD_AES_256_GCM'])); +default_algorithms(mac) -> + supported_algorithms(mac, same(['AEAD_AES_128_GCM', + 'AEAD_AES_256_GCM'])); default_algorithms(Alg) -> - supported_algorithms(Alg). + supported_algorithms(Alg, []). supported_algorithms() -> [{K,supported_algorithms(K)} || K <- algo_classes()]. @@ -97,19 +106,25 @@ supported_algorithms(public_key) -> supported_algorithms(cipher) -> same( select_crypto_supported( - [{'aes256-ctr', [{ciphers,{aes_ctr,256}}]}, - {'aes192-ctr', [{ciphers,{aes_ctr,192}}]}, - {'aes128-ctr', [{ciphers,{aes_ctr,128}}]}, - {'aes128-cbc', [{ciphers,aes_cbc128}]}, - {'3des-cbc', [{ciphers,des3_cbc}]} + [{'aes256-ctr', [{ciphers,{aes_ctr,256}}]}, + {'aes192-ctr', [{ciphers,{aes_ctr,192}}]}, + {'aes128-ctr', [{ciphers,{aes_ctr,128}}]}, + {'aes128-cbc', [{ciphers,aes_cbc128}]}, + {'[email protected]', [{ciphers,{aes_gcm,128}}]}, + {'[email protected]', [{ciphers,{aes_gcm,256}}]}, + {'AEAD_AES_128_GCM', [{ciphers,{aes_gcm,128}}]}, + {'AEAD_AES_256_GCM', [{ciphers,{aes_gcm,256}}]}, + {'3des-cbc', [{ciphers,des3_cbc}]} ] )); supported_algorithms(mac) -> same( select_crypto_supported( - [{'hmac-sha2-256', [{hashs,sha256}]}, - {'hmac-sha2-512', [{hashs,sha512}]}, - {'hmac-sha1', [{hashs,sha}]} + [{'hmac-sha2-256', [{hashs,sha256}]}, + {'hmac-sha2-512', [{hashs,sha512}]}, + {'hmac-sha1', [{hashs,sha}]}, + {'AEAD_AES_128_GCM', [{ciphers,{aes_gcm,128}}]}, + {'AEAD_AES_256_GCM', [{ciphers,{aes_gcm,256}}]} ] )); supported_algorithms(compression) -> @@ -118,46 +133,6 @@ supported_algorithms(compression) -> 'zlib' ]). -%% Dialyzer complains when not called...supported_algorithms(Key, [{client2server,BL1},{server2client,BL2}]) -> -%% Dialyzer complains when not called... [{client2server,As1},{server2client,As2}] = supported_algorithms(Key), -%% Dialyzer complains when not called... [{client2server,As1--BL1},{server2client,As2--BL2}]; -%% Dialyzer complains when not called...supported_algorithms(Key, BlackList) -> -%% Dialyzer complains when not called... supported_algorithms(Key) -- BlackList. - -select_crypto_supported(L) -> - Sup = [{ec_curve,crypto_supported_curves()} | crypto:supports()], - [Name || {Name,CryptoRequires} <- L, - crypto_supported(CryptoRequires, Sup)]. - -crypto_supported_curves() -> - try crypto:ec_curves() - catch _:_ -> [] - end. - -crypto_supported(Conditions, Supported) -> - lists:all( fun({Tag,CryptoName}) when is_atom(CryptoName) -> - crypto_name_supported(Tag,CryptoName,Supported); - ({Tag,{Name=aes_ctr,Len}}) when is_integer(Len) -> - crypto_name_supported(Tag,Name,Supported) andalso - ctr_len_supported(Name,Len) - end, Conditions). - -crypto_name_supported(Tag, CryptoName, Supported) -> - lists:member(CryptoName, proplists:get_value(Tag,Supported,[])). - -ctr_len_supported(Name, Len) -> - try - crypto:stream_encrypt(crypto:stream_init(Name, <<0:Len>>, <<0:128>>), <<"">>) - of - {_,X} -> is_binary(X) - catch - _:_ -> false - end. - - -same(Algs) -> [{client2server,Algs}, {server2client,Algs}]. - - %%%---------------------------------------------------------------------------- versions(client, Options)-> Vsn = proplists:get_value(vsn, Options, ?DEFAULT_CLIENT_VERSION), @@ -196,12 +171,6 @@ hello_version_msg(Data) -> next_seqnum(SeqNum) -> (SeqNum + 1) band 16#ffffffff. -decrypt_first_block(Bin, #ssh{decrypt_block_size = BlockSize} = Ssh0) -> - <<EncBlock:BlockSize/binary, EncData/binary>> = Bin, - {Ssh, <<?UINT32(PacketLen), _/binary>> = DecData} = - decrypt(Ssh0, EncBlock), - {Ssh, PacketLen, DecData, EncData}. - decrypt_blocks(Bin, Length, Ssh0) -> <<EncBlocks:Length/binary, EncData/binary>> = Bin, {Ssh, DecData} = decrypt(Ssh0, EncBlocks), @@ -464,6 +433,40 @@ handle_kex_dh_gex_request(#ssh_msg_kex_dh_gex_request{min = Min0, language = ""}) end; +handle_kex_dh_gex_request(#ssh_msg_kex_dh_gex_request_old{n = NBits}, + Ssh0=#ssh{opts=Opts}) -> + %% server + %% + %% This message was in the draft-00 of rfc4419 + %% (https://tools.ietf.org/html/draft-ietf-secsh-dh-group-exchange-00) + %% In later drafts and the rfc is "is used for backward compatibility". + %% Unfortunatly the rfc does not specify how to treat the parameter n + %% if there is no group of that modulus length :( + %% The draft-00 however specifies that n is the "... number of bits + %% the subgroup should have at least". + %% Further, it says that "Servers and clients SHOULD support groups + %% with a modulus length of k bits, where 1024 <= k <= 8192." + %% + Min0 = NBits, + Max0 = 8192, + {Min, Max} = adjust_gex_min_max(Min0, Max0, Opts), + case public_key:dh_gex_group(Min, NBits, Max, + proplists:get_value(dh_gex_groups,Opts)) of + {ok, {_Sz, {G,P}}} -> + {Public, Private} = generate_key(dh, [P,G]), + {SshPacket, Ssh} = + ssh_packet(#ssh_msg_kex_dh_gex_group{p = P, g = G}, Ssh0), + {ok, SshPacket, + Ssh#ssh{keyex_key = {{Private, Public}, {G, P}}, + keyex_info = {-1, -1, NBits} % flag for kex_h hash calc + }}; + {error,_} -> + throw(#ssh_msg_disconnect{ + code = ?SSH_DISCONNECT_PROTOCOL_ERROR, + description = "No possible diffie-hellman-group-exchange group found", + language = ""}) + end; + handle_kex_dh_gex_request(_, _) -> throw({{error,bad_ssh_msg_kex_dh_gex_request}, #ssh_msg_disconnect{ @@ -757,8 +760,12 @@ known_host_key(#ssh{opts = Opts, key_cb = Mod, peer = Peer} = Ssh, %% The first algorithm in each list MUST be the preferred (guessed) %% algorithm. Each string MUST contain at least one algorithm name. select_algorithm(Role, Client, Server) -> - {Encrypt, Decrypt} = select_encrypt_decrypt(Role, Client, Server), - {SendMac, RecvMac} = select_send_recv_mac(Role, Client, Server), + {Encrypt0, Decrypt0} = select_encrypt_decrypt(Role, Client, Server), + {SendMac0, RecvMac0} = select_send_recv_mac(Role, Client, Server), + + {Encrypt, SendMac} = aead_gcm_simultan(Encrypt0, SendMac0), + {Decrypt, RecvMac} = aead_gcm_simultan(Decrypt0, RecvMac0), + {Compression, Decompression} = select_compression_decompression(Role, Client, Server), @@ -789,6 +796,38 @@ select_algorithm(Role, Client, Server) -> s_lng = S_Lng}, {ok, Alg}. + +%%% It is an agreed problem with RFC 5674 that if the selection is +%%% Cipher = AEAD_AES_x_GCM and +%%% Mac = AEAD_AES_y_GCM (where x =/= y) +%%% then it is undefined what length should be selected. +%%% +%%% If only one of the two lengths (128,256) is available, I claim that +%%% there is no such ambiguity. + +%%% From https://anongit.mindrot.org/openssh.git/plain/PROTOCOL +%%% (read Nov 20, 2015) +%%% 1.6 transport: AES-GCM +%%% +%%% OpenSSH supports the AES-GCM algorithm as specified in RFC 5647. +%%% Because of problems with the specification of the key exchange +%%% the behaviour of OpenSSH differs from the RFC as follows: +%%% +%%% AES-GCM is only negotiated as the cipher algorithms +%%% "[email protected]" or "[email protected]" and never as +%%% an MAC algorithm. Additionally, if AES-GCM is selected as the cipher +%%% the exchanged MAC algorithms are ignored and there doesn't have to be +%%% a matching MAC. + +aead_gcm_simultan('[email protected]', _) -> {'AEAD_AES_128_GCM', 'AEAD_AES_128_GCM'}; +aead_gcm_simultan('[email protected]', _) -> {'AEAD_AES_256_GCM', 'AEAD_AES_256_GCM'}; +aead_gcm_simultan('AEAD_AES_128_GCM', _) -> {'AEAD_AES_128_GCM', 'AEAD_AES_128_GCM'}; +aead_gcm_simultan('AEAD_AES_256_GCM', _) -> {'AEAD_AES_256_GCM', 'AEAD_AES_256_GCM'}; +aead_gcm_simultan(_, 'AEAD_AES_128_GCM') -> {'AEAD_AES_128_GCM', 'AEAD_AES_128_GCM'}; +aead_gcm_simultan(_, 'AEAD_AES_256_GCM') -> {'AEAD_AES_256_GCM', 'AEAD_AES_256_GCM'}; +aead_gcm_simultan(Cipher, Mac) -> {Cipher,Mac}. + + select_encrypt_decrypt(client, Client, Server) -> Encrypt = select(Client#ssh_msg_kexinit.encryption_algorithms_client_to_server, @@ -823,18 +862,18 @@ select_compression_decompression(client, Client, Server) -> Compression = select(Client#ssh_msg_kexinit.compression_algorithms_client_to_server, Server#ssh_msg_kexinit.compression_algorithms_client_to_server), - Decomprssion = + Decompression = select(Client#ssh_msg_kexinit.compression_algorithms_server_to_client, Server#ssh_msg_kexinit.compression_algorithms_server_to_client), - {Compression, Decomprssion}; + {Compression, Decompression}; select_compression_decompression(server, Client, Server) -> - Decomprssion = + Decompression = select(Client#ssh_msg_kexinit.compression_algorithms_client_to_server, Server#ssh_msg_kexinit.compression_algorithms_client_to_server), Compression = select(Client#ssh_msg_kexinit.compression_algorithms_server_to_client, Server#ssh_msg_kexinit.compression_algorithms_server_to_client), - {Compression, Decomprssion}. + {Compression, Decompression}. install_alg(SSH) -> SSH1 = alg_final(SSH), @@ -911,14 +950,39 @@ pack(Data, Ssh=#ssh{}) -> %%% Note: pack/3 is only to be called from tests that wants %%% to deliberetly send packets with wrong PacketLength! %%% Use pack/2 for all other purposes! -pack(Data0, #ssh{encrypt_block_size = BlockSize, - send_sequence = SeqNum, send_mac = MacAlg, - send_mac_key = MacKey, - random_length_padding = RandomLengthPadding} - = Ssh0, - PacketLenDeviationForTests) when is_binary(Data0) -> - {Ssh1, Data} = compress(Ssh0, Data0), - PL = (BlockSize - ((4 + 1 + size(Data)) rem BlockSize)) rem BlockSize, +pack(PlainText, + #ssh{send_sequence = SeqNum, + send_mac = MacAlg, + send_mac_key = MacKey, + encrypt = CryptoAlg} = Ssh0, PacketLenDeviationForTests) when is_binary(PlainText) -> + + {Ssh1, CompressedPlainText} = compress(Ssh0, PlainText), + {EcryptedPacket, MAC, Ssh3} = + case pkt_type(CryptoAlg) of + common -> + PaddingLen = padding_length(4+1+size(CompressedPlainText), Ssh0), + Padding = ssh_bits:random(PaddingLen), + PlainPacketLen = 1 + PaddingLen + size(CompressedPlainText) + PacketLenDeviationForTests, + PlainPacketData = <<?UINT32(PlainPacketLen),?BYTE(PaddingLen), CompressedPlainText/binary, Padding/binary>>, + {Ssh2, EcryptedPacket0} = encrypt(Ssh1, PlainPacketData), + MAC0 = mac(MacAlg, MacKey, SeqNum, PlainPacketData), + {EcryptedPacket0, MAC0, Ssh2}; + aead -> + PaddingLen = padding_length(1+size(CompressedPlainText), Ssh0), + Padding = ssh_bits:random(PaddingLen), + PlainPacketLen = 1 + PaddingLen + size(CompressedPlainText) + PacketLenDeviationForTests, + PlainPacketData = <<?BYTE(PaddingLen), CompressedPlainText/binary, Padding/binary>>, + {Ssh2, {EcryptedPacket0,MAC0}} = encrypt(Ssh1, {<<?UINT32(PlainPacketLen)>>,PlainPacketData}), + {<<?UINT32(PlainPacketLen),EcryptedPacket0/binary>>, MAC0, Ssh2} + end, + FinalPacket = [EcryptedPacket, MAC], + Ssh = Ssh3#ssh{send_sequence = (SeqNum+1) band 16#ffffffff}, + {FinalPacket, Ssh}. + + +padding_length(Size, #ssh{encrypt_block_size = BlockSize, + random_length_padding = RandomLengthPadding}) -> + PL = (BlockSize - (Size rem BlockSize)) rem BlockSize, MinPaddingLen = if PL < 4 -> PL + BlockSize; true -> PL end, @@ -927,45 +991,94 @@ pack(Data0, #ssh{encrypt_block_size = BlockSize, ExtraPaddingLen = try crypto:rand_uniform(0,MaxExtraBlocks)*PadBlockSize catch _:_ -> 0 end, - PaddingLen = MinPaddingLen + ExtraPaddingLen, - Padding = ssh_bits:random(PaddingLen), - PacketLen = 1 + PaddingLen + size(Data) + PacketLenDeviationForTests, - PacketData = <<?UINT32(PacketLen),?BYTE(PaddingLen), - Data/binary, Padding/binary>>, - {Ssh2, EncPacket} = encrypt(Ssh1, PacketData), - MAC = mac(MacAlg, MacKey, SeqNum, PacketData), - Packet = [EncPacket, MAC], - Ssh = Ssh2#ssh{send_sequence = (SeqNum+1) band 16#ffffffff}, - {Packet, Ssh}. - -unpack(EncodedSoFar, ReminingLenght, #ssh{recv_mac_size = MacSize} = Ssh0) -> - SshLength = ReminingLenght - MacSize, - {NoMac, Mac, Rest} = case MacSize of - 0 -> - <<NoMac0:SshLength/binary, - Rest0/binary>> = EncodedSoFar, - {NoMac0, <<>>, Rest0}; - _ -> - <<NoMac0:SshLength/binary, - Mac0:MacSize/binary, - Rest0/binary>> = EncodedSoFar, - {NoMac0, Mac0, Rest0} - end, - {Ssh1, DecData, <<>>} = - case SshLength of - 0 -> - {Ssh0, <<>>, <<>>}; - _ -> - decrypt_blocks(NoMac, SshLength, Ssh0) - end, - {Ssh1, DecData, Rest, Mac}. + MinPaddingLen + ExtraPaddingLen. + + + +handle_packet_part(<<>>, Encrypted0, undefined, #ssh{decrypt = CryptoAlg} = Ssh0) -> + %% New ssh packet + case get_length(pkt_type(CryptoAlg), Encrypted0, Ssh0) of + get_more -> + %% too short to get the length + {get_more, <<>>, Encrypted0, undefined, Ssh0}; -msg_data(PacketData) -> - <<Len:32, PaddingLen:8, _/binary>> = PacketData, - DataLen = Len - PaddingLen - 1, - <<_:32, _:8, Data:DataLen/binary, - _:PaddingLen/binary>> = PacketData, - Data. + {ok, PacketLen, _, _, _} when PacketLen > ?SSH_MAX_PACKET_SIZE -> + %% far too long message than expected + throw(#ssh_msg_disconnect{code = ?SSH_DISCONNECT_PROTOCOL_ERROR, + description = "Bad packet length " + ++ integer_to_list(PacketLen), + language = ""}); + + {ok, PacketLen, Decrypted, Encrypted1, + #ssh{recv_mac_size = MacSize} = Ssh1} -> + %% enough bytes so we got the length and can calculate how many + %% more bytes to expect for a full packet + TotalNeeded = (4 + PacketLen + MacSize), + handle_packet_part(Decrypted, Encrypted1, TotalNeeded, Ssh1) + end; + +handle_packet_part(DecryptedPfx, EncryptedBuffer, TotalNeeded, Ssh0) + when (size(DecryptedPfx)+size(EncryptedBuffer)) < TotalNeeded -> + %% need more bytes to finalize the packet + {get_more, DecryptedPfx, EncryptedBuffer, TotalNeeded, Ssh0}; + +handle_packet_part(DecryptedPfx, EncryptedBuffer, TotalNeeded, + #ssh{recv_mac_size = MacSize, + decrypt = CryptoAlg} = Ssh0) -> + %% enough bytes to decode the packet. + DecryptLen = TotalNeeded - size(DecryptedPfx) - MacSize, + <<EncryptedSfx:DecryptLen/binary, Mac:MacSize/binary, NextPacketBytes/binary>> = EncryptedBuffer, + case pkt_type(CryptoAlg) of + common -> + {Ssh1, DecryptedSfx} = decrypt(Ssh0, EncryptedSfx), + DecryptedPacket = <<DecryptedPfx/binary, DecryptedSfx/binary>>, + case is_valid_mac(Mac, DecryptedPacket, Ssh1) of + false -> + {bad_mac, Ssh1}; + true -> + {Ssh, DecompressedPayload} = decompress(Ssh1, payload(DecryptedPacket)), + {decoded, DecompressedPayload, NextPacketBytes, Ssh} + end; + aead -> + PacketLenBin = DecryptedPfx, + case decrypt(Ssh0, {PacketLenBin,EncryptedSfx,Mac}) of + {Ssh1, error} -> + {bad_mac, Ssh1}; + {Ssh1, DecryptedSfx} -> + DecryptedPacket = <<DecryptedPfx/binary, DecryptedSfx/binary>>, + {Ssh, DecompressedPayload} = decompress(Ssh1, payload(DecryptedPacket)), + {decoded, DecompressedPayload, NextPacketBytes, Ssh} + end + end. + + +get_length(common, EncryptedBuffer, #ssh{decrypt_block_size = BlockSize} = Ssh0) -> + case size(EncryptedBuffer) >= erlang:max(8, BlockSize) of + true -> + <<EncBlock:BlockSize/binary, EncryptedRest/binary>> = EncryptedBuffer, + {Ssh, + <<?UINT32(PacketLen),_/binary>> = Decrypted} = decrypt(Ssh0, EncBlock), + {ok, PacketLen, Decrypted, EncryptedRest, Ssh}; + false -> + get_more + end; +get_length(aead, EncryptedBuffer, Ssh) -> + case size(EncryptedBuffer) >= 4 of + true -> + <<?UINT32(PacketLen), EncryptedRest/binary>> = EncryptedBuffer, + {ok, PacketLen, <<?UINT32(PacketLen)>>, EncryptedRest, Ssh}; + false -> + get_more + end. + +pkt_type('AEAD_AES_128_GCM') -> aead; +pkt_type('AEAD_AES_256_GCM') -> aead; +pkt_type(_) -> common. + +payload(<<PacketLen:32, PaddingLen:8, PayloadAndPadding/binary>>) -> + PayloadLen = PacketLen - PaddingLen - 1, + <<Payload:PayloadLen/binary, _/binary>> = PayloadAndPadding, + Payload. sign(SigData, Hash, #'DSAPrivateKey'{} = Key) -> DerSignature = public_key:sign(SigData, Hash, Key), @@ -991,6 +1104,7 @@ verify(PlainText, Hash, Sig, {#'ECPoint'{},_} = Key) -> verify(PlainText, Hash, Sig, Key) -> public_key:verify(PlainText, Hash, Sig, Key). + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% %% Encryption @@ -999,6 +1113,30 @@ verify(PlainText, Hash, Sig, Key) -> encrypt_init(#ssh{encrypt = none} = Ssh) -> {ok, Ssh}; +encrypt_init(#ssh{encrypt = 'AEAD_AES_128_GCM', role = client} = Ssh) -> + IV = hash(Ssh, "A", 12*8), + <<K:16/binary>> = hash(Ssh, "C", 128), + {ok, Ssh#ssh{encrypt_keys = K, + encrypt_block_size = 16, + encrypt_ctx = IV}}; +encrypt_init(#ssh{encrypt = 'AEAD_AES_128_GCM', role = server} = Ssh) -> + IV = hash(Ssh, "B", 12*8), + <<K:16/binary>> = hash(Ssh, "D", 128), + {ok, Ssh#ssh{encrypt_keys = K, + encrypt_block_size = 16, + encrypt_ctx = IV}}; +encrypt_init(#ssh{encrypt = 'AEAD_AES_256_GCM', role = client} = Ssh) -> + IV = hash(Ssh, "A", 12*8), + <<K:32/binary>> = hash(Ssh, "C", 256), + {ok, Ssh#ssh{encrypt_keys = K, + encrypt_block_size = 16, + encrypt_ctx = IV}}; +encrypt_init(#ssh{encrypt = 'AEAD_AES_256_GCM', role = server} = Ssh) -> + IV = hash(Ssh, "B", 12*8), + <<K:32/binary>> = hash(Ssh, "D", 256), + {ok, Ssh#ssh{encrypt_keys = K, + encrypt_block_size = 16, + encrypt_ctx = IV}}; encrypt_init(#ssh{encrypt = '3des-cbc', role = client} = Ssh) -> IV = hash(Ssh, "A", 64), <<K1:8/binary, K2:8/binary, K3:8/binary>> = hash(Ssh, "C", 192), @@ -1075,6 +1213,18 @@ encrypt_final(Ssh) -> encrypt(#ssh{encrypt = none} = Ssh, Data) -> {Ssh, Data}; +encrypt(#ssh{encrypt = 'AEAD_AES_128_GCM', + encrypt_keys = K, + encrypt_ctx = IV0} = Ssh, Data={_AAD,_Ptext}) -> + Enc = {_Ctext,_Ctag} = crypto:block_encrypt(aes_gcm, K, IV0, Data), + IV = next_gcm_iv(IV0), + {Ssh#ssh{encrypt_ctx = IV}, Enc}; +encrypt(#ssh{encrypt = 'AEAD_AES_256_GCM', + encrypt_keys = K, + encrypt_ctx = IV0} = Ssh, Data={_AAD,_Ptext}) -> + Enc = {_Ctext,_Ctag} = crypto:block_encrypt(aes_gcm, K, IV0, Data), + IV = next_gcm_iv(IV0), + {Ssh#ssh{encrypt_ctx = IV}, Enc}; encrypt(#ssh{encrypt = '3des-cbc', encrypt_keys = {K1,K2,K3}, encrypt_ctx = IV0} = Ssh, Data) -> @@ -1107,6 +1257,30 @@ encrypt(#ssh{encrypt = 'aes256-ctr', decrypt_init(#ssh{decrypt = none} = Ssh) -> {ok, Ssh}; +decrypt_init(#ssh{decrypt = 'AEAD_AES_128_GCM', role = client} = Ssh) -> + IV = hash(Ssh, "B", 12*8), + <<K:16/binary>> = hash(Ssh, "D", 128), + {ok, Ssh#ssh{decrypt_keys = K, + decrypt_block_size = 16, + decrypt_ctx = IV}}; +decrypt_init(#ssh{decrypt = 'AEAD_AES_128_GCM', role = server} = Ssh) -> + IV = hash(Ssh, "A", 12*8), + <<K:16/binary>> = hash(Ssh, "C", 128), + {ok, Ssh#ssh{decrypt_keys = K, + decrypt_block_size = 16, + decrypt_ctx = IV}}; +decrypt_init(#ssh{decrypt = 'AEAD_AES_256_GCM', role = client} = Ssh) -> + IV = hash(Ssh, "B", 12*8), + <<K:32/binary>> = hash(Ssh, "D", 256), + {ok, Ssh#ssh{decrypt_keys = K, + decrypt_block_size = 16, + decrypt_ctx = IV}}; +decrypt_init(#ssh{decrypt = 'AEAD_AES_256_GCM', role = server} = Ssh) -> + IV = hash(Ssh, "A", 12*8), + <<K:32/binary>> = hash(Ssh, "C", 256), + {ok, Ssh#ssh{decrypt_keys = K, + decrypt_block_size = 16, + decrypt_ctx = IV}}; decrypt_init(#ssh{decrypt = '3des-cbc', role = client} = Ssh) -> {IV, KD} = {hash(Ssh, "B", 64), hash(Ssh, "D", 192)}, @@ -1181,8 +1355,22 @@ decrypt_final(Ssh) -> decrypt_ctx = undefined, decrypt_block_size = 8}}. +decrypt(Ssh, <<>>) -> + {Ssh, <<>>}; decrypt(#ssh{decrypt = none} = Ssh, Data) -> {Ssh, Data}; +decrypt(#ssh{decrypt = 'AEAD_AES_128_GCM', + decrypt_keys = K, + decrypt_ctx = IV0} = Ssh, Data = {_AAD,_Ctext,_Ctag}) -> + Dec = crypto:block_decrypt(aes_gcm, K, IV0, Data), % Dec = PlainText | error + IV = next_gcm_iv(IV0), + {Ssh#ssh{decrypt_ctx = IV}, Dec}; +decrypt(#ssh{decrypt = 'AEAD_AES_256_GCM', + decrypt_keys = K, + decrypt_ctx = IV0} = Ssh, Data = {_AAD,_Ctext,_Ctag}) -> + Dec = crypto:block_decrypt(aes_gcm, K, IV0, Data), % Dec = PlainText | error + IV = next_gcm_iv(IV0), + {Ssh#ssh{decrypt_ctx = IV}, Dec}; decrypt(#ssh{decrypt = '3des-cbc', decrypt_keys = Keys, decrypt_ctx = IV0} = Ssh, Data) -> {K1, K2, K3} = Keys, @@ -1207,6 +1395,10 @@ decrypt(#ssh{decrypt = 'aes256-ctr', {State, Enc} = crypto:stream_decrypt(State0,Data), {Ssh#ssh{decrypt_ctx = State}, Enc}. + +next_gcm_iv(<<Fixed:32, InvCtr:64>>) -> <<Fixed:32, (InvCtr+1):64>>. + + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% Compression %% @@ -1295,28 +1487,42 @@ decompress(#ssh{decompress = '[email protected]', decompress_ctx = Context, authe %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% send_mac_init(SSH) -> - case SSH#ssh.role of - client -> - KeySize =mac_key_size(SSH#ssh.send_mac), - Key = hash(SSH, "E", KeySize), - {ok, SSH#ssh { send_mac_key = Key }}; - server -> - KeySize = mac_key_size(SSH#ssh.send_mac), - Key = hash(SSH, "F", KeySize), - {ok, SSH#ssh { send_mac_key = Key }} + case pkt_type(SSH#ssh.send_mac) of + common -> + case SSH#ssh.role of + client -> + KeySize = mac_key_size(SSH#ssh.send_mac), + Key = hash(SSH, "E", KeySize), + {ok, SSH#ssh { send_mac_key = Key }}; + server -> + KeySize = mac_key_size(SSH#ssh.send_mac), + Key = hash(SSH, "F", KeySize), + {ok, SSH#ssh { send_mac_key = Key }} + end; + aead -> + %% Not applicable + {ok, SSH} end. send_mac_final(SSH) -> - {ok, SSH#ssh { send_mac = none, send_mac_key = undefined }}. + {ok, SSH#ssh {send_mac = none, + send_mac_key = undefined }}. + recv_mac_init(SSH) -> - case SSH#ssh.role of - client -> - Key = hash(SSH, "F", mac_key_size(SSH#ssh.recv_mac)), - {ok, SSH#ssh { recv_mac_key = Key }}; - server -> - Key = hash(SSH, "E", mac_key_size(SSH#ssh.recv_mac)), - {ok, SSH#ssh { recv_mac_key = Key }} + case pkt_type(SSH#ssh.recv_mac) of + common -> + case SSH#ssh.role of + client -> + Key = hash(SSH, "F", mac_key_size(SSH#ssh.recv_mac)), + {ok, SSH#ssh { recv_mac_key = Key }}; + server -> + Key = hash(SSH, "E", mac_key_size(SSH#ssh.recv_mac)), + {ok, SSH#ssh { recv_mac_key = Key }} + end; + aead -> + %% Not applicable + {ok, SSH} end. recv_mac_final(SSH) -> @@ -1399,8 +1605,11 @@ kex_h(SSH, Curve, Key, Q_c, Q_s, K) -> crypto:hash(sha(Curve), L). kex_h(SSH, Key, Min, NBits, Max, Prime, Gen, E, F, K) -> + KeyBin = public_key:ssh_encode(Key, ssh2_pubkey), L = if Min==-1; Max==-1 -> - KeyBin = public_key:ssh_encode(Key, ssh2_pubkey), + %% flag from 'ssh_msg_kex_dh_gex_request_old' + %% It was like this before that message was supported, + %% why? Ts = [string,string,binary,binary,binary, uint32, mpint,mpint,mpint,mpint,mpint], @@ -1409,7 +1618,6 @@ kex_h(SSH, Key, Min, NBits, Max, Prime, Gen, E, F, K) -> KeyBin, NBits, Prime, Gen, E,F,K], Ts); true -> - KeyBin = public_key:ssh_encode(Key, ssh2_pubkey), Ts = [string,string,binary,binary,binary, uint32,uint32,uint32, mpint,mpint,mpint,mpint,mpint], @@ -1447,6 +1655,8 @@ mac_digest_size('hmac-md5') -> 20; mac_digest_size('hmac-md5-96') -> 12; mac_digest_size('hmac-sha2-256') -> 32; mac_digest_size('hmac-sha2-512') -> 64; +mac_digest_size('AEAD_AES_128_GCM') -> 16; +mac_digest_size('AEAD_AES_256_GCM') -> 16; mac_digest_size(none) -> 0. peer_name({Host, _}) -> @@ -1476,6 +1686,68 @@ ecdh_curve('ecdh-sha2-nistp256') -> secp256r1; ecdh_curve('ecdh-sha2-nistp384') -> secp384r1; ecdh_curve('ecdh-sha2-nistp521') -> secp521r1. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% +%% Utils for default_algorithms/1 and supported_algorithms/1 +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +supported_algorithms(Key, [{client2server,BL1},{server2client,BL2}]) -> + [{client2server,As1},{server2client,As2}] = supported_algorithms(Key), + [{client2server,As1--BL1},{server2client,As2--BL2}]; +supported_algorithms(Key, BlackList) -> + supported_algorithms(Key) -- BlackList. + + +select_crypto_supported(L) -> + Sup = [{ec_curve,crypto_supported_curves()} | crypto:supports()], + [Name || {Name,CryptoRequires} <- L, + crypto_supported(CryptoRequires, Sup)]. + +crypto_supported_curves() -> + try crypto:ec_curves() + catch _:_ -> [] + end. + +crypto_supported(Conditions, Supported) -> + lists:all( fun({Tag,CryptoName}) when is_atom(CryptoName) -> + crypto_name_supported(Tag,CryptoName,Supported); + ({Tag,{Name,Len}}) when is_integer(Len) -> + crypto_name_supported(Tag,Name,Supported) andalso + len_supported(Name,Len) + end, Conditions). + +crypto_name_supported(Tag, CryptoName, Supported) -> + lists:member(CryptoName, proplists:get_value(Tag,Supported,[])). + +len_supported(Name, Len) -> + try + case Name of + aes_ctr -> + {_, <<_/binary>>} = + %% Test encryption + crypto:stream_encrypt(crypto:stream_init(Name, <<0:Len>>, <<0:128>>), <<"">>); + aes_gcm -> + {<<_/binary>>, <<_/binary>>} = + crypto:block_encrypt(Name, + _Key = <<0:Len>>, + _IV = <<0:12/unsigned-unit:8>>, + {<<"AAD">>,"PT"}) + end + of + _ -> true + catch + _:_ -> false + end. + + +same(Algs) -> [{client2server,Algs}, {server2client,Algs}]. + + +%% default_algorithms(kex) -> % Example of how to disable an algorithm +%% supported_algorithms(kex, ['ecdh-sha2-nistp521']); + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% %% Other utils diff --git a/lib/ssh/test/Makefile b/lib/ssh/test/Makefile index 96c74c6c8a..781a876723 100644 --- a/lib/ssh/test/Makefile +++ b/lib/ssh/test/Makefile @@ -47,6 +47,8 @@ MODULES= \ ssh_to_openssh_SUITE \ ssh_upgrade_SUITE \ ssh_test_lib \ + ssh_key_cb \ + ssh_key_cb_options \ ssh_trpt_test_lib \ ssh_echo_server \ ssh_peername_sockname_server \ diff --git a/lib/ssh/test/ssh_algorithms_SUITE.erl b/lib/ssh/test/ssh_algorithms_SUITE.erl index 85415a17de..f0ac92fef6 100644 --- a/lib/ssh/test/ssh_algorithms_SUITE.erl +++ b/lib/ssh/test/ssh_algorithms_SUITE.erl @@ -69,6 +69,9 @@ two_way_tags() -> [cipher,mac,compression]. %%-------------------------------------------------------------------- init_per_suite(Config) -> + ct:log("os:getenv(\"HOME\") = ~p~n" + "init:get_argument(home) = ~p", + [os:getenv("HOME"), init:get_argument(home)]), ct:log("~n~n" "OS ssh:~n=======~n~p~n~n~n" "Erl ssh:~n========~n~p~n~n~n" @@ -358,7 +361,9 @@ start_pubkey_daemon(Opts, Config) -> setup_pubkey(Config) -> DataDir = ?config(data_dir, Config), UserDir = ?config(priv_dir, Config), - ssh_test_lib:setup_dsa_known_host(DataDir, UserDir), + ssh_test_lib:setup_dsa(DataDir, UserDir), + ssh_test_lib:setup_rsa(DataDir, UserDir), + ssh_test_lib:setup_ecdsa("256", DataDir, UserDir), Config. diff --git a/lib/ssh/test/ssh_algorithms_SUITE_data/id_ecdsa b/lib/ssh/test/ssh_algorithms_SUITE_data/id_ecdsa new file mode 100644 index 0000000000..4b1eb12eaa --- /dev/null +++ b/lib/ssh/test/ssh_algorithms_SUITE_data/id_ecdsa @@ -0,0 +1,5 @@ +-----BEGIN EC PRIVATE KEY----- +MHcCAQEEIJfCaBKIIKhjbJl5F8BedqlXOQYDX5ba9Skypllmx/w+oAoGCCqGSM49 +AwEHoUQDQgAE49RbK2xQ/19ji3uDPM7uT4692LbwWF1TiaA9vUuebMGazoW/98br +N9xZu0L1AWwtEjs3kmJDTB7eJEGXnjUAcQ== +-----END EC PRIVATE KEY----- diff --git a/lib/ssh/test/ssh_algorithms_SUITE_data/id_ecdsa.pub b/lib/ssh/test/ssh_algorithms_SUITE_data/id_ecdsa.pub new file mode 100644 index 0000000000..a0147e60fa --- /dev/null +++ b/lib/ssh/test/ssh_algorithms_SUITE_data/id_ecdsa.pub @@ -0,0 +1 @@ +ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBOPUWytsUP9fY4t7gzzO7k+Ovdi28FhdU4mgPb1LnmzBms6Fv/fG6zfcWbtC9QFsLRI7N5JiQ0we3iRBl541AHE= uabhnil@elxadlj3q32 diff --git a/lib/ssh/test/ssh_algorithms_SUITE_data/id_ecdsa256 b/lib/ssh/test/ssh_algorithms_SUITE_data/id_ecdsa256 new file mode 100644 index 0000000000..4b1eb12eaa --- /dev/null +++ b/lib/ssh/test/ssh_algorithms_SUITE_data/id_ecdsa256 @@ -0,0 +1,5 @@ +-----BEGIN EC PRIVATE KEY----- +MHcCAQEEIJfCaBKIIKhjbJl5F8BedqlXOQYDX5ba9Skypllmx/w+oAoGCCqGSM49 +AwEHoUQDQgAE49RbK2xQ/19ji3uDPM7uT4692LbwWF1TiaA9vUuebMGazoW/98br +N9xZu0L1AWwtEjs3kmJDTB7eJEGXnjUAcQ== +-----END EC PRIVATE KEY----- diff --git a/lib/ssh/test/ssh_algorithms_SUITE_data/id_ecdsa256.pub b/lib/ssh/test/ssh_algorithms_SUITE_data/id_ecdsa256.pub new file mode 100644 index 0000000000..a0147e60fa --- /dev/null +++ b/lib/ssh/test/ssh_algorithms_SUITE_data/id_ecdsa256.pub @@ -0,0 +1 @@ +ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBOPUWytsUP9fY4t7gzzO7k+Ovdi28FhdU4mgPb1LnmzBms6Fv/fG6zfcWbtC9QFsLRI7N5JiQ0we3iRBl541AHE= uabhnil@elxadlj3q32 diff --git a/lib/ssh/test/ssh_algorithms_SUITE_data/ssh_host_ecdsa_key256 b/lib/ssh/test/ssh_algorithms_SUITE_data/ssh_host_ecdsa_key256 new file mode 100644 index 0000000000..2979ea88ed --- /dev/null +++ b/lib/ssh/test/ssh_algorithms_SUITE_data/ssh_host_ecdsa_key256 @@ -0,0 +1,5 @@ +-----BEGIN EC PRIVATE KEY----- +MHcCAQEEIMe4MDoit0t8RzSVPwkCBemQ9fhXL+xnTSAWISw8HNCioAoGCCqGSM49 +AwEHoUQDQgAEo2q7U3P6r0W5WGOLtM78UQtofM9UalEhiZeDdiyylsR/RR17Op0s +VPGSADLmzzgcucLEKy17j2S+oz42VUJy5A== +-----END EC PRIVATE KEY----- diff --git a/lib/ssh/test/ssh_algorithms_SUITE_data/ssh_host_ecdsa_key256.pub b/lib/ssh/test/ssh_algorithms_SUITE_data/ssh_host_ecdsa_key256.pub new file mode 100644 index 0000000000..85dc419345 --- /dev/null +++ b/lib/ssh/test/ssh_algorithms_SUITE_data/ssh_host_ecdsa_key256.pub @@ -0,0 +1 @@ +ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBKNqu1Nz+q9FuVhji7TO/FELaHzPVGpRIYmXg3YsspbEf0UdezqdLFTxkgAy5s84HLnCxCste49kvqM+NlVCcuQ= uabhnil@elxadlj3q32 diff --git a/lib/ssh/test/ssh_basic_SUITE.erl b/lib/ssh/test/ssh_basic_SUITE.erl index 400edb4d2c..85a6bac972 100644 --- a/lib/ssh/test/ssh_basic_SUITE.erl +++ b/lib/ssh/test/ssh_basic_SUITE.erl @@ -36,9 +36,15 @@ cli/1, close/1, daemon_already_started/1, + daemon_opt_fd/1, + multi_daemon_opt_fd/1, double_close/1, exec/1, exec_compressed/1, + exec_key_differs1/1, + exec_key_differs2/1, + exec_key_differs3/1, + exec_key_differs_fail/1, idle_time/1, inet6_option/1, inet_option/1, @@ -52,8 +58,10 @@ send/1, shell/1, shell_no_unicode/1, - shell_unicode_string/1, - ssh_info_print/1 + shell_unicode_string/1, + ssh_info_print/1, + key_callback/1, + key_callback_options/1 ]). %%% Common test callbacks @@ -82,9 +90,13 @@ all() -> {group, ecdsa_sha2_nistp521_key}, {group, dsa_pass_key}, {group, rsa_pass_key}, + {group, host_user_key_differs}, + {group, key_cb}, {group, internal_error}, daemon_already_started, double_close, + daemon_opt_fd, + multi_daemon_opt_fd, packet_size_zero, ssh_info_print ]. @@ -95,8 +107,13 @@ groups() -> {ecdsa_sha2_nistp256_key, [], basic_tests()}, {ecdsa_sha2_nistp384_key, [], basic_tests()}, {ecdsa_sha2_nistp521_key, [], basic_tests()}, + {host_user_key_differs, [], [exec_key_differs1, + exec_key_differs2, + exec_key_differs3, + exec_key_differs_fail]}, {dsa_pass_key, [], [pass_phrase]}, {rsa_pass_key, [], [pass_phrase]}, + {key_cb, [], [key_callback, key_callback_options]}, {internal_error, [], [internal_error]} ]. @@ -176,6 +193,26 @@ init_per_group(dsa_pass_key, Config) -> PrivDir = ?config(priv_dir, Config), ssh_test_lib:setup_dsa_pass_pharse(DataDir, PrivDir, "Password"), [{pass_phrase, {dsa_pass_phrase, "Password"}}| Config]; +init_per_group(host_user_key_differs, Config) -> + Data = ?config(data_dir, Config), + Sys = filename:join(?config(priv_dir, Config), system_rsa), + SysUsr = filename:join(Sys, user), + Usr = filename:join(?config(priv_dir, Config), user_ecdsa_256), + file:make_dir(Sys), + file:make_dir(SysUsr), + file:make_dir(Usr), + file:copy(filename:join(Data, "ssh_host_rsa_key"), filename:join(Sys, "ssh_host_rsa_key")), + file:copy(filename:join(Data, "ssh_host_rsa_key.pub"), filename:join(Sys, "ssh_host_rsa_key.pub")), + file:copy(filename:join(Data, "id_ecdsa256"), filename:join(Usr, "id_ecdsa")), + file:copy(filename:join(Data, "id_ecdsa256.pub"), filename:join(Usr, "id_ecdsa.pub")), + ssh_test_lib:setup_ecdsa_auth_keys("256", Usr, SysUsr), + ssh_test_lib:setup_rsa_known_host(Sys, Usr), + Config; +init_per_group(key_cb, Config) -> + DataDir = ?config(data_dir, Config), + PrivDir = ?config(priv_dir, Config), + ssh_test_lib:setup_dsa(DataDir, PrivDir), + Config; init_per_group(internal_error, Config) -> DataDir = ?config(data_dir, Config), PrivDir = ?config(priv_dir, Config), @@ -243,6 +280,10 @@ end_per_group(rsa_pass_key, Config) -> PrivDir = ?config(priv_dir, Config), ssh_test_lib:clean_rsa(PrivDir), Config; +end_per_group(key_cb, Config) -> + PrivDir = ?config(priv_dir, Config), + ssh_test_lib:clean_dsa(PrivDir), + Config; end_per_group(internal_error, Config) -> PrivDir = ?config(priv_dir, Config), ssh_test_lib:clean_dsa(PrivDir), @@ -474,6 +515,80 @@ shell(Config) when is_list(Config) -> end. %%-------------------------------------------------------------------- +%%% Test that we could user different types of host pubkey and user pubkey +exec_key_differs1(Config) -> exec_key_differs(Config, ['ecdsa-sha2-nistp256']). + +exec_key_differs2(Config) -> exec_key_differs(Config, ['ssh-dss','ecdsa-sha2-nistp256']). + +exec_key_differs3(Config) -> exec_key_differs(Config, ['ecdsa-sha2-nistp384','ecdsa-sha2-nistp256']). + + + +exec_key_differs(Config, UserPKAlgs) -> + case lists:usort(['ssh-rsa'|UserPKAlgs]) + -- ssh_transport:supported_algorithms(public_key) + of + [] -> + process_flag(trap_exit, true), + SystemDir = filename:join(?config(priv_dir, Config), system_rsa), + SystemUserDir = filename:join(SystemDir, user), + UserDir = filename:join(?config(priv_dir, Config), user_ecdsa_256), + + {_Pid, _Host, Port} = ssh_test_lib:daemon([{system_dir, SystemDir}, + {user_dir, SystemUserDir}, + {preferred_algorithms, + [{public_key,['ssh-rsa']}]}]), + ct:sleep(500), + + IO = ssh_test_lib:start_io_server(), + Shell = ssh_test_lib:start_shell(Port, IO, UserDir, + [{preferred_algorithms,[{public_key,['ssh-rsa']}]}, + {pref_public_key_algs,UserPKAlgs} + ]), + + + receive + {'EXIT', _, _} -> + ct:fail(no_ssh_connection); + ErlShellStart -> + ct:log("Erlang shell start: ~p~n", [ErlShellStart]), + do_shell(IO, Shell) + after + 30000 -> ct:fail("timeout ~p:~p",[?MODULE,?LINE]) + end; + + UnsupportedPubKeys -> + {skip, io_lib:format("~p unsupported",[UnsupportedPubKeys])} + end. + +%%-------------------------------------------------------------------- +exec_key_differs_fail(Config) when is_list(Config) -> + process_flag(trap_exit, true), + SystemDir = filename:join(?config(priv_dir, Config), system_rsa), + SystemUserDir = filename:join(SystemDir, user), + UserDir = filename:join(?config(priv_dir, Config), user_ecdsa_256), + + {_Pid, _Host, Port} = ssh_test_lib:daemon([{system_dir, SystemDir}, + {user_dir, SystemUserDir}, + {preferred_algorithms, + [{public_key,['ssh-rsa']}]}]), + ct:sleep(500), + + IO = ssh_test_lib:start_io_server(), + ssh_test_lib:start_shell(Port, IO, UserDir, + [{preferred_algorithms,[{public_key,['ssh-rsa']}]}, + {pref_public_key_algs,['ssh-dss']}]), + receive + {'EXIT', _, _} -> + ok; + ErlShellStart -> + ct:log("Erlang shell start: ~p~n", [ErlShellStart]), + ct:fail(connection_not_rejected) + after + 30000 -> ct:fail("timeout ~p:~p",[?MODULE,?LINE]) + end. + +%%-------------------------------------------------------------------- cli(Config) when is_list(Config) -> process_flag(trap_exit, true), SystemDir = filename:join(?config(priv_dir, Config), system), @@ -571,6 +686,56 @@ pass_phrase(Config) when is_list(Config) -> {ok, _ChannelId} = ssh_connection:session_channel(ConnectionRef, infinity), ssh:stop_daemon(Pid). +%%-------------------------------------------------------------------- +%%% Test that we can use key callback +key_callback(Config) when is_list(Config) -> + process_flag(trap_exit, true), + SystemDir = filename:join(?config(priv_dir, Config), system), + UserDir = ?config(priv_dir, Config), + NoPubKeyDir = filename:join(UserDir, "nopubkey"), + file:make_dir(NoPubKeyDir), + + {Pid, Host, Port} = ssh_test_lib:daemon([{system_dir, SystemDir}, + {user_dir, UserDir}, + {failfun, fun ssh_test_lib:failfun/2}]), + + ConnectOpts = [{silently_accept_hosts, true}, + {user_dir, NoPubKeyDir}, + {user_interaction, false}, + {key_cb, ssh_key_cb}], + + ConnectionRef = ssh_test_lib:connect(Host, Port, ConnectOpts), + + {ok, _ChannelId} = ssh_connection:session_channel(ConnectionRef, infinity), + ssh:stop_daemon(Pid). + + +%%-------------------------------------------------------------------- +%%% Test that we can use key callback with callback options +key_callback_options(Config) when is_list(Config) -> + process_flag(trap_exit, true), + SystemDir = filename:join(?config(priv_dir, Config), system), + UserDir = ?config(priv_dir, Config), + + NoPubKeyDir = filename:join(UserDir, "nopubkey"), + file:make_dir(NoPubKeyDir), + + {Pid, Host, Port} = ssh_test_lib:daemon([{system_dir, SystemDir}, + {user_dir, UserDir}, + {failfun, fun ssh_test_lib:failfun/2}]), + + {ok, PrivKey} = file:read_file(filename:join(UserDir, "id_dsa")), + + ConnectOpts = [{silently_accept_hosts, true}, + {user_dir, NoPubKeyDir}, + {user_interaction, false}, + {key_cb, {ssh_key_cb_options, [{priv_key, PrivKey}]}}], + + ConnectionRef = ssh_test_lib:connect(Host, Port, ConnectOpts), + + {ok, _ChannelId} = ssh_connection:session_channel(ConnectionRef, infinity), + ssh:stop_daemon(Pid). + %%-------------------------------------------------------------------- %%% Test that client does not hang if disconnects due to internal error @@ -705,6 +870,68 @@ double_close(Config) when is_list(Config) -> ok = ssh:close(CM). %%-------------------------------------------------------------------- +daemon_opt_fd(Config) -> + SystemDir = ?config(data_dir, Config), + PrivDir = ?config(priv_dir, Config), + UserDir = filename:join(PrivDir, nopubkey), % to make sure we don't use public-key-auth + file:make_dir(UserDir), + + {ok,S1} = gen_tcp:listen(0,[]), + {ok,Fd1} = prim_inet:getfd(S1), + + {ok,Pid1} = ssh:daemon(0, [{system_dir, SystemDir}, + {fd,Fd1}, + {user_dir, UserDir}, + {user_passwords, [{"vego", "morot"}]}, + {failfun, fun ssh_test_lib:failfun/2}]), + + {ok,{_Host1,Port1}} = inet:sockname(S1), + {ok, C1} = ssh:connect("localhost", Port1, [{silently_accept_hosts, true}, + {user_dir, UserDir}, + {user, "vego"}, + {password, "morot"}, + {user_interaction, false}]), + exit(C1, {shutdown, normal}), + ssh:stop_daemon(Pid1), + gen_tcp:close(S1). + + +%%-------------------------------------------------------------------- +multi_daemon_opt_fd(Config) -> + SystemDir = ?config(data_dir, Config), + PrivDir = ?config(priv_dir, Config), + UserDir = filename:join(PrivDir, nopubkey), % to make sure we don't use public-key-auth + file:make_dir(UserDir), + + Test = + fun() -> + {ok,S} = gen_tcp:listen(0,[]), + {ok,Fd} = prim_inet:getfd(S), + + {ok,Pid} = ssh:daemon(0, [{system_dir, SystemDir}, + {fd,Fd}, + {user_dir, UserDir}, + {user_passwords, [{"vego", "morot"}]}, + {failfun, fun ssh_test_lib:failfun/2}]), + + {ok,{_Host,Port}} = inet:sockname(S), + {ok, C} = ssh:connect("localhost", Port, [{silently_accept_hosts, true}, + {user_dir, UserDir}, + {user, "vego"}, + {password, "morot"}, + {user_interaction, false}]), + {S,Pid,C} + end, + + Tests = [Test(),Test(),Test(),Test(),Test(),Test()], + + [begin + gen_tcp:close(S), + ssh:stop_daemon(Pid), + exit(C, {shutdown, normal}) + end || {S,Pid,C} <- Tests]. + +%%-------------------------------------------------------------------- packet_size_zero(Config) -> SystemDir = ?config(data_dir, Config), PrivDir = ?config(priv_dir, Config), diff --git a/lib/ssh/test/ssh_key_cb.erl b/lib/ssh/test/ssh_key_cb.erl new file mode 100644 index 0000000000..388ec2ecc1 --- /dev/null +++ b/lib/ssh/test/ssh_key_cb.erl @@ -0,0 +1,45 @@ +%% +%% %CopyrightBegin% +%% +%% Copyright Ericsson AB 2015. All Rights Reserved. +%% +%% Licensed under the Apache License, Version 2.0 (the "License"); +%% you may not use this file except in compliance with the License. +%% You may obtain a copy of the License at +%% +%% http://www.apache.org/licenses/LICENSE-2.0 +%% +%% Unless required by applicable law or agreed to in writing, software +%% distributed under the License is distributed on an "AS IS" BASIS, +%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +%% See the License for the specific language governing permissions and +%% limitations under the License. +%% +%% %CopyrightEnd% +%% + +%% +%%---------------------------------------------------------------------- + +%% Note: This module is used by ssh_basic_SUITE + +-module(ssh_key_cb). +-behaviour(ssh_client_key_api). +-compile(export_all). + +add_host_key(_, _, _) -> + ok. + +is_host_key(_, _, _, _) -> + true. + +user_key('ssh-dss', Opts) -> + UserDir = proplists:get_value(user_dir, Opts), + KeyFile = filename:join(filename:dirname(UserDir), "id_dsa"), + {ok, KeyBin} = file:read_file(KeyFile), + [Entry] = public_key:pem_decode(KeyBin), + Key = public_key:pem_entry_decode(Entry), + {ok, Key}; + +user_key(_Alg, _Opt) -> + {error, "Not Supported"}. diff --git a/lib/ssh/test/ssh_key_cb_options.erl b/lib/ssh/test/ssh_key_cb_options.erl new file mode 100644 index 0000000000..afccb34f0f --- /dev/null +++ b/lib/ssh/test/ssh_key_cb_options.erl @@ -0,0 +1,44 @@ +%% +%% %CopyrightBegin% +%% +%% Copyright Ericsson AB 2015. All Rights Reserved. +%% +%% Licensed under the Apache License, Version 2.0 (the "License"); +%% you may not use this file except in compliance with the License. +%% You may obtain a copy of the License at +%% +%% http://www.apache.org/licenses/LICENSE-2.0 +%% +%% Unless required by applicable law or agreed to in writing, software +%% distributed under the License is distributed on an "AS IS" BASIS, +%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +%% See the License for the specific language governing permissions and +%% limitations under the License. +%% +%% %CopyrightEnd% +%% + +%% +%%---------------------------------------------------------------------- + +%% Note: This module is used by ssh_basic_SUITE + +-module(ssh_key_cb_options). +-behaviour(ssh_client_key_api). +-compile(export_all). + +add_host_key(_, _, _) -> + ok. + +is_host_key(_, _, _, _) -> + true. + +user_key('ssh-dss', Opts) -> + KeyCbOpts = proplists:get_value(key_cb_private, Opts), + KeyBin = proplists:get_value(priv_key, KeyCbOpts), + [Entry] = public_key:pem_decode(KeyBin), + Key = public_key:pem_entry_decode(Entry), + {ok, Key}; + +user_key(_Alg, _Opt) -> + {error, "Not Supported"}. diff --git a/lib/ssh/test/ssh_protocol_SUITE.erl b/lib/ssh/test/ssh_protocol_SUITE.erl index 3a7f47c2dd..4639904061 100644 --- a/lib/ssh/test/ssh_protocol_SUITE.erl +++ b/lib/ssh/test/ssh_protocol_SUITE.erl @@ -69,7 +69,9 @@ groups() -> gex_client_init_option_groups, gex_server_gex_limit, gex_client_init_option_groups_moduli_file, - gex_client_init_option_groups_file + gex_client_init_option_groups_file, + gex_client_old_request_exact, + gex_client_old_request_noexact ]}, {service_requests, [], [bad_service_name, bad_long_service_name, @@ -94,7 +96,9 @@ init_per_testcase(no_common_alg_server_disconnects, Config) -> init_per_testcase(TC, Config) when TC == gex_client_init_option_groups ; TC == gex_client_init_option_groups_moduli_file ; TC == gex_client_init_option_groups_file ; - TC == gex_server_gex_limit -> + TC == gex_server_gex_limit ; + TC == gex_client_old_request_exact ; + TC == gex_client_old_request_noexact -> Opts = case TC of gex_client_init_option_groups -> [{dh_gex_groups, [{2345, 3, 41}]}]; @@ -106,8 +110,10 @@ init_per_testcase(TC, Config) when TC == gex_client_init_option_groups ; DataDir = ?config(data_dir, Config), F = filename:join(DataDir, "dh_group_test.moduli"), [{dh_gex_groups, {ssh_moduli_file,F}}]; - gex_server_gex_limit -> - [{dh_gex_groups, [{ 500, 3, 18}, + _ when TC == gex_server_gex_limit ; + TC == gex_client_old_request_exact ; + TC == gex_client_old_request_noexact -> + [{dh_gex_groups, [{ 500, 3, 17}, {1000, 7, 91}, {3000, 5, 61}]}, {dh_gex_limits,{500,1500}} @@ -126,7 +132,9 @@ end_per_testcase(no_common_alg_server_disconnects, Config) -> end_per_testcase(TC, Config) when TC == gex_client_init_option_groups ; TC == gex_client_init_option_groups_moduli_file ; TC == gex_client_init_option_groups_file ; - TC == gex_server_gex_limit -> + TC == gex_server_gex_limit ; + TC == gex_client_old_request_exact ; + TC == gex_client_old_request_noexact -> stop_std_daemon(Config); end_per_testcase(_TestCase, Config) -> check_std_daemon_works(Config, ?LINE). @@ -381,6 +389,29 @@ do_gex_client_init(Config, {Min,N,Max}, {G,P}) -> ] ). +%%%-------------------------------------------------------------------- +gex_client_old_request_exact(Config) -> do_gex_client_init_old(Config, 500, {3,17}). +gex_client_old_request_noexact(Config) -> do_gex_client_init_old(Config, 800, {7,91}). + +do_gex_client_init_old(Config, N, {G,P}) -> + {ok,_} = + ssh_trpt_test_lib:exec( + [{set_options, [print_ops, print_seqnums, print_messages]}, + {connect, + server_host(Config),server_port(Config), + [{silently_accept_hosts, true}, + {user_dir, user_dir(Config)}, + {user_interaction, false}, + {preferred_algorithms,[{kex,['diffie-hellman-group-exchange-sha1']}]} + ]}, + receive_hello, + {send, hello}, + {send, ssh_msg_kexinit}, + {match, #ssh_msg_kexinit{_='_'}, receive_msg}, + {send, #ssh_msg_kex_dh_gex_request_old{n = N}}, + {match, #ssh_msg_kex_dh_gex_group{p=P, g=G, _='_'}, receive_msg} + ] + ). %%%-------------------------------------------------------------------- bad_service_name(Config) -> diff --git a/lib/ssh/test/ssh_renegotiate_SUITE.erl b/lib/ssh/test/ssh_renegotiate_SUITE.erl index ef631d54bd..e5cfa58bad 100644 --- a/lib/ssh/test/ssh_renegotiate_SUITE.erl +++ b/lib/ssh/test/ssh_renegotiate_SUITE.erl @@ -32,9 +32,15 @@ suite() -> [{ct_hooks,[ts_install_cth]}]. -all() -> [rekey, rekey_limit, renegotiate1, renegotiate2]. +all() -> [{group,default_algs}, + {group,aes_gcm} + ]. -groups() -> []. +groups() -> [{default_algs, [], tests()}, + {aes_gcm, [], tests()} + ]. + +tests() -> [rekey, rekey_limit, renegotiate1, renegotiate2]. %%-------------------------------------------------------------------- init_per_suite(Config) -> @@ -50,6 +56,24 @@ end_per_suite(_Config) -> crypto:stop(). %%-------------------------------------------------------------------- +init_per_group(aes_gcm, Config) -> + case lists:member({client2server,['[email protected]']}, + ssh_transport:supported_algorithms(cipher)) of + true -> + [{preferred_algorithms, [{cipher,[{client2server,['[email protected]']}, + {server2client,['[email protected]']}]}]} + | Config]; + false -> + {skip, "aes_gcm not supported"} + end; +init_per_group(_, Config) -> + [{preferred_algorithms, ssh:default_algorithms()} | Config]. + + +end_per_group(_, Config) -> + Config. + +%%-------------------------------------------------------------------- init_per_testcase(_TestCase, Config) -> ssh:start(), Config. @@ -89,7 +113,9 @@ rekey_limit(Config) -> UserDir = ?config(priv_dir, Config), DataFile = filename:join(UserDir, "rekey.data"), - {Pid, Host, Port} = ssh_test_lib:std_daemon(Config,[{max_random_length_padding,0}]), + Algs = ?config(preferred_algorithms, Config), + {Pid, Host, Port} = ssh_test_lib:std_daemon(Config,[{max_random_length_padding,0}, + {preferred_algorithms,Algs}]), ConnectionRef = ssh_test_lib:std_connect(Config, Host, Port, [{rekey_limit, 6000}, {max_random_length_padding,0}]), @@ -133,7 +159,9 @@ renegotiate1(Config) -> UserDir = ?config(priv_dir, Config), DataFile = filename:join(UserDir, "renegotiate1.data"), - {Pid, Host, DPort} = ssh_test_lib:std_daemon(Config,[{max_random_length_padding,0}]), + Algs = ?config(preferred_algorithms, Config), + {Pid, Host, DPort} = ssh_test_lib:std_daemon(Config,[{max_random_length_padding,0}, + {preferred_algorithms,Algs}]), RPort = ssh_test_lib:inet_port(), {ok,RelayPid} = ssh_relay:start_link({0,0,0,0}, RPort, Host, DPort), @@ -171,7 +199,9 @@ renegotiate2(Config) -> UserDir = ?config(priv_dir, Config), DataFile = filename:join(UserDir, "renegotiate2.data"), - {Pid, Host, DPort} = ssh_test_lib:std_daemon(Config,[{max_random_length_padding,0}]), + Algs = ?config(preferred_algorithms, Config), + {Pid, Host, DPort} = ssh_test_lib:std_daemon(Config,[{max_random_length_padding,0}, + {preferred_algorithms,Algs}]), RPort = ssh_test_lib:inet_port(), {ok,RelayPid} = ssh_relay:start_link({0,0,0,0}, RPort, Host, DPort), diff --git a/lib/ssh/test/ssh_test_lib.erl b/lib/ssh/test/ssh_test_lib.erl index 5816b708f2..424afc76fe 100644 --- a/lib/ssh/test/ssh_test_lib.erl +++ b/lib/ssh/test/ssh_test_lib.erl @@ -296,7 +296,7 @@ setup_dsa(DataDir, UserDir) -> file:make_dir(System), file:copy(filename:join(DataDir, "ssh_host_dsa_key"), filename:join(System, "ssh_host_dsa_key")), file:copy(filename:join(DataDir, "ssh_host_dsa_key.pub"), filename:join(System, "ssh_host_dsa_key.pub")), -ct:pal("DataDir ~p:~n ~p~n~nSystDir ~p:~n ~p~n~nUserDir ~p:~n ~p",[DataDir, file:list_dir(DataDir), System, file:list_dir(System), UserDir, file:list_dir(UserDir)]), +ct:log("DataDir ~p:~n ~p~n~nSystDir ~p:~n ~p~n~nUserDir ~p:~n ~p",[DataDir, file:list_dir(DataDir), System, file:list_dir(System), UserDir, file:list_dir(UserDir)]), setup_dsa_known_host(DataDir, UserDir), setup_dsa_auth_keys(DataDir, UserDir). @@ -306,7 +306,7 @@ setup_rsa(DataDir, UserDir) -> file:make_dir(System), file:copy(filename:join(DataDir, "ssh_host_rsa_key"), filename:join(System, "ssh_host_rsa_key")), file:copy(filename:join(DataDir, "ssh_host_rsa_key.pub"), filename:join(System, "ssh_host_rsa_key.pub")), -ct:pal("DataDir ~p:~n ~p~n~nSystDir ~p:~n ~p~n~nUserDir ~p:~n ~p",[DataDir, file:list_dir(DataDir), System, file:list_dir(System), UserDir, file:list_dir(UserDir)]), +ct:log("DataDir ~p:~n ~p~n~nSystDir ~p:~n ~p~n~nUserDir ~p:~n ~p",[DataDir, file:list_dir(DataDir), System, file:list_dir(System), UserDir, file:list_dir(UserDir)]), setup_rsa_known_host(DataDir, UserDir), setup_rsa_auth_keys(DataDir, UserDir). @@ -316,7 +316,7 @@ setup_ecdsa(Size, DataDir, UserDir) -> file:make_dir(System), file:copy(filename:join(DataDir, "ssh_host_ecdsa_key"++Size), filename:join(System, "ssh_host_ecdsa_key")), file:copy(filename:join(DataDir, "ssh_host_ecdsa_key"++Size++".pub"), filename:join(System, "ssh_host_ecdsa_key.pub")), -ct:pal("DataDir ~p:~n ~p~n~nSystDir ~p:~n ~p~n~nUserDir ~p:~n ~p",[DataDir, file:list_dir(DataDir), System, file:list_dir(System), UserDir, file:list_dir(UserDir)]), +ct:log("DataDir ~p:~n ~p~n~nSystDir ~p:~n ~p~n~nUserDir ~p:~n ~p",[DataDir, file:list_dir(DataDir), System, file:list_dir(System), UserDir, file:list_dir(UserDir)]), setup_ecdsa_known_host(Size, System, UserDir), setup_ecdsa_auth_keys(Size, UserDir, UserDir). @@ -502,7 +502,7 @@ default_algorithms(sshd, Host, Port) -> {user_interaction, false}]}])) catch _C:_E -> - ct:pal("***~p:~p: ~p:~p",[?MODULE,?LINE,_C,_E]), + ct:log("***~p:~p: ~p:~p",[?MODULE,?LINE,_C,_E]), [] end. @@ -522,7 +522,7 @@ default_algorithms(sshc, DaemonOptions) -> InitialState)) catch _C:_E -> - ct:pal("***~p:~p: ~p:~p",[?MODULE,?LINE,_C,_E]), + ct:log("***~p:~p: ~p:~p",[?MODULE,?LINE,_C,_E]), [] end} end), diff --git a/lib/ssh/vsn.mk b/lib/ssh/vsn.mk index d828bccd29..25b19133b1 100644 --- a/lib/ssh/vsn.mk +++ b/lib/ssh/vsn.mk @@ -1,4 +1,5 @@ #-*-makefile-*- ; force emacs to enter makefile-mode SSH_VSN = 4.2 + APP_VSN = "ssh-$(SSH_VSN)" diff --git a/lib/ssl/doc/src/notes.xml b/lib/ssl/doc/src/notes.xml index 6faa3d5f9a..4d4a219b4f 100644 --- a/lib/ssl/doc/src/notes.xml +++ b/lib/ssl/doc/src/notes.xml @@ -26,8 +26,9 @@ <file>notes.xml</file> </header> <p>This document describes the changes made to the SSL application.</p> - <section><title>SSL 7.1</title> + +<section><title>SSL 7.1</title> <section><title>Fixed Bugs and Malfunctions</title> <list> <item> @@ -107,12 +108,6 @@ <p> Own Id: OTP-12815</p> </item> - <item> - <p> - Gracefully ignore proprietary hash_sign algorithms</p> - <p> - Own Id: OTP-12829</p> - </item> </list> </section> @@ -163,6 +158,20 @@ </section> +<section><title>SSL 6.0.1.1</title> + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Gracefully ignore proprietary hash_sign algorithms</p> + <p> + Own Id: OTP-12829</p> + </item> + </list> + </section> +</section> + + <section><title>SSL 6.0.1</title> <section><title>Fixed Bugs and Malfunctions</title> diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index 22ac98c24e..3a541ed162 100644 --- a/lib/ssl/doc/src/ssl.xml +++ b/lib/ssl/doc/src/ssl.xml @@ -84,7 +84,7 @@ <seealso marker="kernel:gen_tcp">gen_tcp(3)</seealso> manual pages in Kernel.</p></item> - <tag><marker id="type-ssloption"></marker><c>ssloption() =</c></tag> + <tag><marker id="type-ssloption"/><c>ssloption() =</c></tag> <item> <p><c>{verify, verify_type()}</c></p> <p><c>| {verify_fun, {fun(), term()}}</c></p> @@ -160,7 +160,7 @@ <tag><c>sslsocket() =</c></tag> <item><p>opaque()</p></item> - <tag><c>protocol() =</c></tag> + <tag><marker id="type-protocol"/><c>protocol() =</c></tag> <item><p><c>sslv3 | tlsv1 | 'tlsv1.1' | 'tlsv1.2'</c></p></item> <tag><c>ciphers() =</c></tag> diff --git a/lib/ssl/doc/src/ssl_app.xml b/lib/ssl/doc/src/ssl_app.xml index 51ce0cedf1..24b0f5300e 100644 --- a/lib/ssl/doc/src/ssl_app.xml +++ b/lib/ssl/doc/src/ssl_app.xml @@ -58,7 +58,7 @@ <p><c>erl -ssl protocol_version "['tlsv1.2', 'tlsv1.1']"</c></p> <taglist> - <tag><c><![CDATA[protocol_version = <seealso marker="kernel:error_logger">ssl:protocol()</seealso> <optional>]]></c>.</tag> + <tag><c> protocol_version = <seealso marker="ssl#type-protocol">ssl:protocol()</seealso> <![CDATA[<optional>]]></c></tag> <item><p>Protocol supported by started clients and servers. If this option is not set, it defaults to all protocols currently supported by the SSL application. @@ -66,17 +66,24 @@ to <c>ssl:connect/[2,3]</c> and <c>ssl:listen/2</c>.</p></item> <tag><c><![CDATA[session_lifetime = integer() <optional>]]></c></tag> - <item><p>Lifetime of the session data in seconds.</p></item> + <item><p>Maximum lifetime of the session data in seconds.</p></item> <tag><c><![CDATA[session_cb = atom() <optional>]]></c></tag> <item><p>Name of the session cache callback module that implements the <c>ssl_session_cache_api</c> behavior. Defaults to - <c>ssl_session_cache.erl</c>.</p></item> + <c>ssl_session_cache</c>.</p></item> <tag><c><![CDATA[session_cb_init_args = proplist:proplist() <optional>]]></c></tag> <item><p>List of extra user-defined arguments to the <c>init</c> function in the session cache callback module. Defaults to <c>[]</c>.</p></item> + + <tag><c><![CDATA[session_cache_client_max = integer() <optional>]]></c></tag> + <tag><c><![CDATA[session_cache_server_max = integer() <optional>]]></c></tag> + <item><p>Limits the growth of the clients/servers session cache, + if the maximum number of sessions is reached, the current cache entries will + be invalidated regardless of their remaining lifetime. Defaults to 1000. + </p></item> <tag><c><![CDATA[ssl_pem_cache_clean = integer() <optional>]]></c></tag> <item> @@ -103,7 +110,10 @@ <section> <title>ERROR LOGGER AND EVENT HANDLERS</title> - <p>The SSL application uses the default <seealso marker="kernel:error_logger">OTP error logger</seealso> to log unexpected errors and TLS alerts. The logging of TLS alerts may be turned off with the <c>log_alert</c> option. </p> + <p>The SSL application uses the default <seealso + marker="kernel:error_logger">OTP error logger</seealso> to log + unexpected errors and TLS alerts. The logging of TLS alerts may be + turned off with the <c>log_alert</c> option. </p> </section> <section> diff --git a/lib/ssl/src/dtls_connection.erl b/lib/ssl/src/dtls_connection.erl index 78662e0ea2..153d3fef48 100644 --- a/lib/ssl/src/dtls_connection.erl +++ b/lib/ssl/src/dtls_connection.erl @@ -145,7 +145,7 @@ init([Role, Host, Port, Socket, {SSLOpts0, _} = Options, User, CbInfo]) -> process_flag(trap_exit, true), State0 = initial_state(Role, Host, Port, Socket, Options, User, CbInfo), Handshake = ssl_handshake:init_handshake_history(), - TimeStamp = calendar:datetime_to_gregorian_seconds({date(), time()}), + TimeStamp = erlang:monotonic_time(), try ssl_config:init(SSLOpts0, Role) of {ok, Ref, CertDbHandle, FileRefHandle, CacheHandle, CRLDbInfo, OwnCert, Key, DHParams} -> Session = State0#state.session, diff --git a/lib/ssl/src/inet_tls_dist.erl b/lib/ssl/src/inet_tls_dist.erl index b6e62a18c9..404ae93d20 100644 --- a/lib/ssl/src/inet_tls_dist.erl +++ b/lib/ssl/src/inet_tls_dist.erl @@ -30,7 +30,7 @@ childspecs() -> {ok, [{ssl_dist_sup,{ssl_dist_sup, start_link, []}, - permanent, 2000, worker, [ssl_dist_sup]}]}. + permanent, infinity, supervisor, [ssl_dist_sup]}]}. select(Node) -> case split_node(atom_to_list(Node), $@, []) of diff --git a/lib/ssl/src/ssl_connection.erl b/lib/ssl/src/ssl_connection.erl index f8afbdb41d..241871dc38 100644 --- a/lib/ssl/src/ssl_connection.erl +++ b/lib/ssl/src/ssl_connection.erl @@ -974,7 +974,7 @@ ssl_config(Opts, Role, State) -> {ok, Ref, CertDbHandle, FileRefHandle, CacheHandle, CRLDbInfo, OwnCert, Key, DHParams} = ssl_config:init(Opts, Role), Handshake = ssl_handshake:init_handshake_history(), - TimeStamp = calendar:datetime_to_gregorian_seconds({date(), time()}), + TimeStamp = erlang:monotonic_time(), Session = State#state.session, State#state{tls_handshake_history = Handshake, session = Session#session{own_certificate = OwnCert, @@ -1781,7 +1781,7 @@ handle_trusted_certs_db(#state{ssl_options = #ssl_options{cacertfile = <<>>, cac ok; handle_trusted_certs_db(#state{cert_db_ref = Ref, cert_db = CertDb, - ssl_options = #ssl_options{cacertfile = <<>>}}) -> + ssl_options = #ssl_options{cacertfile = <<>>}}) when CertDb =/= undefined -> %% Certs provided as DER directly can not be shared %% with other connections and it is safe to delete them when the connection ends. ssl_pkix_db:remove_trusted_certs(Ref, CertDb); diff --git a/lib/ssl/src/ssl_dist_sup.erl b/lib/ssl/src/ssl_dist_sup.erl index aa1fa57db8..435ad27a44 100644 --- a/lib/ssl/src/ssl_dist_sup.erl +++ b/lib/ssl/src/ssl_dist_sup.erl @@ -70,7 +70,7 @@ connection_manager_child_spec() -> Name = ssl_connection_dist, StartFunc = {tls_connection_sup, start_link_dist, []}, Restart = permanent, - Shutdown = 4000, + Shutdown = infinity, Modules = [tls_connection_sup], Type = supervisor, {Name, StartFunc, Restart, Shutdown, Type, Modules}. diff --git a/lib/ssl/src/ssl_internal.hrl b/lib/ssl/src/ssl_internal.hrl index 3851b2bc6e..8c7ed9c0d1 100644 --- a/lib/ssl/src/ssl_internal.hrl +++ b/lib/ssl/src/ssl_internal.hrl @@ -78,6 +78,9 @@ -define(ALL_DATAGRAM_SUPPORTED_VERSIONS, ['dtlsv1.2', dtlsv1]). -define(MIN_DATAGRAM_SUPPORTED_VERSIONS, ['dtlsv1.2', dtlsv1]). +-define('24H_in_msec', 86400000). +-define('24H_in_sec', 86400). + -record(ssl_options, { protocol :: tls | dtls, versions :: [ssl_record:ssl_version()], %% ssl_record:atom_version() in API diff --git a/lib/ssl/src/ssl_manager.erl b/lib/ssl/src/ssl_manager.erl index 2e05ba5aa5..00e95f5c5b 100644 --- a/lib/ssl/src/ssl_manager.erl +++ b/lib/ssl/src/ssl_manager.erl @@ -46,25 +46,27 @@ -include_lib("kernel/include/file.hrl"). -record(state, { - session_cache_client, - session_cache_server, - session_cache_cb, - session_lifetime, - certificate_db, - session_validation_timer, + session_cache_client :: db_handle(), + session_cache_server :: db_handle(), + session_cache_cb :: atom(), + session_lifetime :: integer(), + certificate_db :: db_handle(), + session_validation_timer :: reference(), last_delay_timer = {undefined, undefined},%% Keep for testing purposes - last_pem_check, - clear_pem_cache + last_pem_check :: erlang:timestamp(), + clear_pem_cache :: integer(), + session_cache_client_max :: integer(), + session_cache_server_max :: integer(), + session_server_invalidator :: undefined | pid(), + session_client_invalidator :: undefined | pid() }). --define('24H_in_msec', 86400000). --define('24H_in_sec', 86400). -define(GEN_UNIQUE_ID_MAX_TRIES, 10). -define(SESSION_VALIDATION_INTERVAL, 60000). -define(CLEAR_PEM_CACHE, 120000). -define(CLEAN_SESSION_DB, 60000). -define(CLEAN_CERT_DB, 500). --define(NOT_TO_BIG, 10). +-define(DEFAULT_MAX_SESSION_CACHE, 1000). %%==================================================================== %% API @@ -89,7 +91,8 @@ manager_name(dist) -> %%-------------------------------------------------------------------- start_link(Opts) -> DistMangerName = manager_name(normal), - gen_server:start_link({local, DistMangerName}, ?MODULE, [DistMangerName, Opts], []). + gen_server:start_link({local, DistMangerName}, + ?MODULE, [DistMangerName, Opts], []). %%-------------------------------------------------------------------- -spec start_link_dist(list()) -> {ok, pid()} | ignore | {error, term()}. @@ -99,7 +102,8 @@ start_link(Opts) -> %%-------------------------------------------------------------------- start_link_dist(Opts) -> DistMangerName = manager_name(dist), - gen_server:start_link({local, DistMangerName}, ?MODULE, [DistMangerName, Opts], []). + gen_server:start_link({local, DistMangerName}, + ?MODULE, [DistMangerName, Opts], []). %%-------------------------------------------------------------------- -spec connection_init(binary()| {der, list()}, client | server, @@ -169,7 +173,8 @@ new_session_id(Port) -> %% be called by ssl-connection processes. %%-------------------------------------------------------------------- clean_cert_db(Ref, File) -> - erlang:send_after(?CLEAN_CERT_DB, get(ssl_manager), {clean_cert_db, Ref, File}), + erlang:send_after(?CLEAN_CERT_DB, get(ssl_manager), + {clean_cert_db, Ref, File}), ok. %%-------------------------------------------------------------------- @@ -237,10 +242,12 @@ init([Name, Opts]) -> SessionLifeTime = proplists:get_value(session_lifetime, Opts, ?'24H_in_sec'), CertDb = ssl_pkix_db:create(), - ClientSessionCache = CacheCb:init([{role, client} | - proplists:get_value(session_cb_init_args, Opts, [])]), - ServerSessionCache = CacheCb:init([{role, server} | - proplists:get_value(session_cb_init_args, Opts, [])]), + ClientSessionCache = + CacheCb:init([{role, client} | + proplists:get_value(session_cb_init_args, Opts, [])]), + ServerSessionCache = + CacheCb:init([{role, server} | + proplists:get_value(session_cb_init_args, Opts, [])]), Timer = erlang:send_after(SessionLifeTime * 1000 + 5000, self(), validate_sessions), Interval = pem_check_interval(), @@ -252,7 +259,11 @@ init([Name, Opts]) -> session_lifetime = SessionLifeTime, session_validation_timer = Timer, last_pem_check = os:timestamp(), - clear_pem_cache = Interval + clear_pem_cache = Interval, + session_cache_client_max = + max_session_cache_size(session_cache_client_max), + session_cache_server_max = + max_session_cache_size(session_cache_server_max) }}. %%-------------------------------------------------------------------- @@ -269,7 +280,8 @@ init([Name, Opts]) -> handle_call({{connection_init, <<>>, Role, {CRLCb, UserCRLDb}}, _Pid}, _From, #state{certificate_db = [CertDb, FileRefDb, PemChace | _] = Db} = State) -> Ref = make_ref(), - Result = {ok, Ref, CertDb, FileRefDb, PemChace, session_cache(Role, State), {CRLCb, crl_db_info(Db, UserCRLDb)}}, + Result = {ok, Ref, CertDb, FileRefDb, PemChace, + session_cache(Role, State), {CRLCb, crl_db_info(Db, UserCRLDb)}}, {reply, Result, State#state{certificate_db = Db}}; handle_call({{connection_init, Trustedcerts, Role, {CRLCb, UserCRLDb}}, Pid}, _From, @@ -307,7 +319,8 @@ handle_call({{cache_pem,File}, _Pid}, _, _:Reason -> {reply, {error, Reason}, State} end; -handle_call({unconditionally_clear_pem_cache, _},_, #state{certificate_db = [_,_,PemChace | _]} = State) -> +handle_call({unconditionally_clear_pem_cache, _},_, + #state{certificate_db = [_,_,PemChace | _]} = State) -> ssl_pkix_db:clear(PemChace), {reply, ok, State}. @@ -319,27 +332,12 @@ handle_call({unconditionally_clear_pem_cache, _},_, #state{certificate_db = [_,_ %% %% Description: Handling cast messages %%-------------------------------------------------------------------- -handle_cast({register_session, Host, Port, Session}, - #state{session_cache_client = Cache, - session_cache_cb = CacheCb} = State) -> - TimeStamp = calendar:datetime_to_gregorian_seconds({date(), time()}), - NewSession = Session#session{time_stamp = TimeStamp}, - - case CacheCb:select_session(Cache, {Host, Port}) of - no_session -> - CacheCb:update(Cache, {{Host, Port}, - NewSession#session.session_id}, NewSession); - Sessions -> - register_unique_session(Sessions, NewSession, CacheCb, Cache, {Host, Port}) - end, +handle_cast({register_session, Host, Port, Session}, State0) -> + State = ssl_client_register_session(Host, Port, Session, State0), {noreply, State}; -handle_cast({register_session, Port, Session}, - #state{session_cache_server = Cache, - session_cache_cb = CacheCb} = State) -> - TimeStamp = calendar:datetime_to_gregorian_seconds({date(), time()}), - NewSession = Session#session{time_stamp = TimeStamp}, - CacheCb:update(Cache, {Port, NewSession#session.session_id}, NewSession), +handle_cast({register_session, Port, Session}, State0) -> + State = server_register_session(Port, Session, State0), {noreply, State}; handle_cast({invalidate_session, Host, Port, @@ -413,10 +411,10 @@ handle_info({clean_cert_db, Ref, File}, end, {noreply, State}; -handle_info({'EXIT', _, _}, State) -> - %% Session validator died!! Do we need to take any action? - %% maybe error log - {noreply, State}; +handle_info({'EXIT', Pid, _}, #state{session_client_invalidator = Pid} = State) -> + {noreply, State#state{session_client_invalidator = undefined}}; +handle_info({'EXIT', Pid, _}, #state{session_server_invalidator = Pid} = State) -> + {noreply, State#state{session_server_invalidator = undefined}}; handle_info(_Info, State) -> {noreply, State}. @@ -497,7 +495,15 @@ delay_time() -> ?CLEAN_SESSION_DB end. -invalidate_session(Cache, CacheCb, Key, Session, #state{last_delay_timer = LastTimer} = State) -> +max_session_cache_size(CacheType) -> + case application:get_env(ssl, CacheType) of + {ok, Size} when is_integer(Size) -> + Size; + _ -> + ?DEFAULT_MAX_SESSION_CACHE + end. + +invalidate_session(Cache, CacheCb, Key, Session, State) -> case CacheCb:lookup(Cache, Key) of undefined -> %% Session is already invalidated {noreply, State}; @@ -505,15 +511,23 @@ invalidate_session(Cache, CacheCb, Key, Session, #state{last_delay_timer = LastT CacheCb:delete(Cache, Key), {noreply, State}; _ -> - %% When a registered session is invalidated we need to wait a while before deleting - %% it as there might be pending connections that rightfully needs to look - %% up the session data but new connections should not get to use this session. - CacheCb:update(Cache, Key, Session#session{is_resumable = false}), - TRef = - erlang:send_after(delay_time(), self(), {delayed_clean_session, Key, Cache}), - {noreply, State#state{last_delay_timer = last_delay_timer(Key, TRef, LastTimer)}} + delayed_invalidate_session(CacheCb, Cache, Key, Session, State) end. +delayed_invalidate_session(CacheCb, Cache, Key, Session, + #state{last_delay_timer = LastTimer} = State) -> + %% When a registered session is invalidated we need to + %% wait a while before deleting it as there might be + %% pending connections that rightfully needs to look up + %% the session data but new connections should not get to + %% use this session. + CacheCb:update(Cache, Key, Session#session{is_resumable = false}), + TRef = + erlang:send_after(delay_time(), self(), + {delayed_clean_session, Key, Cache}), + {noreply, State#state{last_delay_timer = + last_delay_timer(Key, TRef, LastTimer)}}. + last_delay_timer({{_,_},_}, TRef, {LastServer, _}) -> {LastServer, TRef}; last_delay_timer({_,_}, TRef, {_, LastClient}) -> @@ -532,12 +546,12 @@ new_id(Port, Tries, Cache, CacheCb) -> Id = crypto:rand_bytes(?NUM_OF_SESSION_ID_BYTES), case CacheCb:lookup(Cache, {Port, Id}) of undefined -> - Now = calendar:datetime_to_gregorian_seconds({date(), time()}), + Now = erlang:monotonic_time(), %% New sessions can not be set to resumable %% until handshake is compleate and the %% other session values are set. CacheCb:update(Cache, {Port, Id}, #session{session_id = Id, - is_resumable = false, + is_resumable = new, time_stamp = Now}), Id; _ -> @@ -559,15 +573,62 @@ clean_cert_db(Ref, CertDb, RefDb, PemCache, File) -> ok end. +ssl_client_register_session(Host, Port, Session, #state{session_cache_client = Cache, + session_cache_cb = CacheCb, + session_cache_client_max = Max, + session_client_invalidator = Pid0} = State) -> + TimeStamp = erlang:monotonic_time(), + NewSession = Session#session{time_stamp = TimeStamp}, + + case CacheCb:select_session(Cache, {Host, Port}) of + no_session -> + Pid = do_register_session({{Host, Port}, + NewSession#session.session_id}, + NewSession, Max, Pid0, Cache, CacheCb), + State#state{session_client_invalidator = Pid}; + Sessions -> + register_unique_session(Sessions, NewSession, {Host, Port}, State) + end. + +server_register_session(Port, Session, #state{session_cache_server_max = Max, + session_cache_server = Cache, + session_cache_cb = CacheCb, + session_server_invalidator = Pid0} = State) -> + TimeStamp = erlang:monotonic_time(), + NewSession = Session#session{time_stamp = TimeStamp}, + Pid = do_register_session({Port, NewSession#session.session_id}, + NewSession, Max, Pid0, Cache, CacheCb), + State#state{session_server_invalidator = Pid}. + +do_register_session(Key, Session, Max, Pid, Cache, CacheCb) -> + try CacheCb:size(Cache) of + N when N > Max -> + invalidate_session_cache(Pid, CacheCb, Cache); + _ -> + CacheCb:update(Cache, Key, Session), + Pid + catch + error:undef -> + CacheCb:update(Cache, Key, Session), + Pid + end. + + %% Do not let dumb clients create a gigantic session table %% for itself creating big delays at connection time. -register_unique_session(Sessions, Session, CacheCb, Cache, PartialKey) -> +register_unique_session(Sessions, Session, PartialKey, + #state{session_cache_client_max = Max, + session_cache_client = Cache, + session_cache_cb = CacheCb, + session_client_invalidator = Pid0} = State) -> case exists_equivalent(Session , Sessions) of true -> - ok; + State; false -> - CacheCb:update(Cache, {PartialKey, - Session#session.session_id}, Session) + Pid = do_register_session({PartialKey, + Session#session.session_id}, + Session, Max, Pid0, Cache, CacheCb), + State#state{session_client_invalidator = Pid} end. exists_equivalent(_, []) -> @@ -622,7 +683,8 @@ pem_check_interval() -> end. is_before_checkpoint(Time, CheckPoint) -> - calendar:datetime_to_gregorian_seconds(calendar:now_to_datetime(CheckPoint)) - + calendar:datetime_to_gregorian_seconds( + calendar:now_to_datetime(CheckPoint)) - calendar:datetime_to_gregorian_seconds(Time) > 0. add_trusted_certs(Pid, Trustedcerts, Db) -> @@ -643,3 +705,9 @@ crl_db_info([_,_,_,Local], {internal, Info}) -> crl_db_info(_, UserCRLDb) -> UserCRLDb. +%% Only start a session invalidator if there is not +%% one already active +invalidate_session_cache(undefined, CacheCb, Cache) -> + start_session_validator(Cache, CacheCb, {invalidate_before, erlang:monotonic_time()}); +invalidate_session_cache(Pid, _CacheCb, _Cache) -> + Pid. diff --git a/lib/ssl/src/ssl_session.erl b/lib/ssl/src/ssl_session.erl index 0d6cc93a20..2b24bff5ff 100644 --- a/lib/ssl/src/ssl_session.erl +++ b/lib/ssl/src/ssl_session.erl @@ -31,8 +31,6 @@ %% Internal application API -export([is_new/2, client_id/4, server_id/6, valid_session/2]). --define('24H_in_sec', 8640). - -type seconds() :: integer(). %%-------------------------------------------------------------------- @@ -63,13 +61,16 @@ client_id(ClientInfo, Cache, CacheCb, OwnCert) -> SessionId end. --spec valid_session(#session{}, seconds()) -> boolean(). +-spec valid_session(#session{}, seconds() | {invalidate_before, integer()}) -> boolean(). %% %% Description: Check that the session has not expired %%-------------------------------------------------------------------- +valid_session(#session{time_stamp = TimeStamp}, {invalidate_before, Before}) -> + TimeStamp > Before; valid_session(#session{time_stamp = TimeStamp}, LifeTime) -> - Now = calendar:datetime_to_gregorian_seconds({date(), time()}), - Now - TimeStamp < LifeTime. + Now = erlang:monotonic_time(), + Lived = erlang:convert_time_unit(Now-TimeStamp, native, seconds), + Lived < LifeTime. server_id(Port, <<>>, _SslOpts, _Cert, _, _) -> {ssl_manager:new_session_id(Port), undefined}; diff --git a/lib/ssl/src/ssl_session_cache.erl b/lib/ssl/src/ssl_session_cache.erl index cfc48cd935..9585e613e6 100644 --- a/lib/ssl/src/ssl_session_cache.erl +++ b/lib/ssl/src/ssl_session_cache.erl @@ -27,7 +27,7 @@ -include("ssl_internal.hrl"). -export([init/1, terminate/1, lookup/2, update/3, delete/2, foldl/3, - select_session/2]). + select_session/2, size/1]). %%-------------------------------------------------------------------- %% Description: Return table reference. Called by ssl_manager process. @@ -86,6 +86,12 @@ select_session(Cache, PartialKey) -> [{{{PartialKey,'_'}, '$1'},[],['$1']}]). %%-------------------------------------------------------------------- +%% Description: Returns the cache size +%%-------------------------------------------------------------------- +size(Cache) -> + ets:info(Cache, size). + +%%-------------------------------------------------------------------- %%% Internal functions %%-------------------------------------------------------------------- cache_name(Name) -> diff --git a/lib/ssl/src/ssl_session_cache_api.erl b/lib/ssl/src/ssl_session_cache_api.erl index 536b52c44b..8f62c25be5 100644 --- a/lib/ssl/src/ssl_session_cache_api.erl +++ b/lib/ssl/src/ssl_session_cache_api.erl @@ -33,3 +33,4 @@ -callback delete(db_handle(), key()) -> any(). -callback foldl(fun(), term(), db_handle()) -> term(). -callback select_session(db_handle(), {host(), inet:port_number()} | inet:port_number()) -> [#session{}]. +-callback size(db_handle()) -> integer(). diff --git a/lib/ssl/src/ssl_tls_dist_proxy.erl b/lib/ssl/src/ssl_tls_dist_proxy.erl index 273d3b5521..d384264b53 100644 --- a/lib/ssl/src/ssl_tls_dist_proxy.erl +++ b/lib/ssl/src/ssl_tls_dist_proxy.erl @@ -48,6 +48,47 @@ accept(Listen) -> connect(Ip, Port) -> gen_server:call(?MODULE, {connect, Ip, Port}, infinity). + +do_listen(Options) -> + {First,Last} = case application:get_env(kernel,inet_dist_listen_min) of + {ok,N} when is_integer(N) -> + case application:get_env(kernel, + inet_dist_listen_max) of + {ok,M} when is_integer(M) -> + {N,M}; + _ -> + {N,N} + end; + _ -> + {0,0} + end, + do_listen(First, Last, listen_options([{backlog,128}|Options])). + +do_listen(First,Last,_) when First > Last -> + {error,eaddrinuse}; +do_listen(First,Last,Options) -> + case gen_tcp:listen(First, Options) of + {error, eaddrinuse} -> + do_listen(First+1,Last,Options); + Other -> + Other + end. + +listen_options(Opts0) -> + Opts1 = + case application:get_env(kernel, inet_dist_use_interface) of + {ok, Ip} -> + [{ip, Ip} | Opts0]; + _ -> + Opts0 + end, + case application:get_env(kernel, inet_dist_listen_options) of + {ok,ListenOpts} -> + ListenOpts ++ Opts1; + _ -> + Opts1 + end. + %%==================================================================== %% gen_server callbacks %%==================================================================== @@ -62,13 +103,17 @@ init([]) -> handle_call({listen, Name}, _From, State) -> case gen_tcp:listen(0, [{active, false}, {packet,?PPRE}]) of {ok, Socket} -> - {ok, World} = gen_tcp:listen(0, [{active, false}, binary, {packet,?PPRE}]), + {ok, World} = do_listen([{active, false}, binary, {packet,?PPRE}, {reuseaddr, true}]), {ok, TcpAddress} = get_tcp_address(Socket), {ok, WorldTcpAddress} = get_tcp_address(World), {_,Port} = WorldTcpAddress#net_address.address, - {ok, Creation} = erl_epmd:register_node(Name, Port), - {reply, {ok, {Socket, TcpAddress, Creation}}, - State#state{listen={Socket, World}}}; + case erl_epmd:register_node(Name, Port) of + {ok, Creation} -> + {reply, {ok, {Socket, TcpAddress, Creation}}, + State#state{listen={Socket, World}}}; + {error, _} = Error -> + {reply, Error, State} + end; Error -> {reply, Error, State} end; @@ -134,6 +179,7 @@ accept_loop(Proxy, erts = Type, Listen, Extra) -> Extra ! {accept,self(),Socket,inet,proxy}, receive {_Kernel, controller, Pid} -> + inet:setopts(Socket, [nodelay()]), ok = gen_tcp:controlling_process(Socket, Pid), flush_old_controller(Pid, Socket), Pid ! {self(), controller}; @@ -167,7 +213,7 @@ accept_loop(Proxy, world = Type, Listen, Extra) -> accept_loop(Proxy, Type, Listen, Extra). try_connect(Port) -> - case gen_tcp:connect({127,0,0,1}, Port, [{active, false}, {packet,?PPRE}]) of + case gen_tcp:connect({127,0,0,1}, Port, [{active, false}, {packet,?PPRE}, nodelay()]) of R = {ok, _S} -> R; {error, _R} -> @@ -177,7 +223,7 @@ try_connect(Port) -> setup_proxy(Ip, Port, Parent) -> process_flag(trap_exit, true), Opts = get_ssl_options(client), - case ssl:connect(Ip, Port, [{active, true}, binary, {packet,?PPRE}] ++ Opts) of + case ssl:connect(Ip, Port, [{active, true}, binary, {packet,?PPRE}, nodelay()] ++ Opts) of {ok, World} -> {ok, ErtsL} = gen_tcp:listen(0, [{active, true}, {ip, {127,0,0,1}}, binary, {packet,?PPRE}]), {ok, #net_address{address={_,LPort}}} = get_tcp_address(ErtsL), @@ -193,25 +239,41 @@ setup_proxy(Ip, Port, Parent) -> Parent ! {self(), Err} end. + +%% we may not always want the nodelay behaviour +%% %% for performance reasons + +nodelay() -> + case application:get_env(kernel, dist_nodelay) of + undefined -> + {nodelay, true}; + {ok, true} -> + {nodelay, true}; + {ok, false} -> + {nodelay, false}; + _ -> + {nodelay, true} + end. + setup_connection(World, ErtsListen) -> process_flag(trap_exit, true), {ok, TcpAddress} = get_tcp_address(ErtsListen), {_Addr,Port} = TcpAddress#net_address.address, - {ok, Erts} = gen_tcp:connect({127,0,0,1}, Port, [{active, true}, binary, {packet,?PPRE}]), - ssl:setopts(World, [{active,true}, {packet,?PPRE}]), + {ok, Erts} = gen_tcp:connect({127,0,0,1}, Port, [{active, true}, binary, {packet,?PPRE}, nodelay()]), + ssl:setopts(World, [{active,true}, {packet,?PPRE}, nodelay()]), loop_conn_setup(World, Erts). loop_conn_setup(World, Erts) -> receive {ssl, World, Data = <<$a, _/binary>>} -> gen_tcp:send(Erts, Data), - ssl:setopts(World, [{packet,?PPOST}]), - inet:setopts(Erts, [{packet,?PPOST}]), + ssl:setopts(World, [{packet,?PPOST}, nodelay()]), + inet:setopts(Erts, [{packet,?PPOST}, nodelay()]), loop_conn(World, Erts); {tcp, Erts, Data = <<$a, _/binary>>} -> ssl:send(World, Data), - ssl:setopts(World, [{packet,?PPOST}]), - inet:setopts(Erts, [{packet,?PPOST}]), + ssl:setopts(World, [{packet,?PPOST}, nodelay()]), + inet:setopts(Erts, [{packet,?PPOST}, nodelay()]), loop_conn(World, Erts); {ssl, World, Data = <<_, _/binary>>} -> gen_tcp:send(Erts, Data), diff --git a/lib/ssl/src/ssl_v3.erl b/lib/ssl/src/ssl_v3.erl index 5e043624a7..f169059a75 100644 --- a/lib/ssl/src/ssl_v3.erl +++ b/lib/ssl/src/ssl_v3.erl @@ -144,6 +144,7 @@ suites() -> ?TLS_DHE_RSA_WITH_AES_128_CBC_SHA, ?TLS_DHE_DSS_WITH_AES_128_CBC_SHA, ?TLS_RSA_WITH_AES_128_CBC_SHA, + ?TLS_DHE_RSA_WITH_DES_CBC_SHA, ?TLS_RSA_WITH_DES_CBC_SHA ]. diff --git a/lib/ssl/src/tls_connection.erl b/lib/ssl/src/tls_connection.erl index 3093508f61..a468c131ce 100644 --- a/lib/ssl/src/tls_connection.erl +++ b/lib/ssl/src/tls_connection.erl @@ -168,9 +168,10 @@ hello(start, #state{host = Host, port = Port, role = client, Cache, CacheCb, Renegotiation, Cert), Version = Hello#client_hello.client_version, + HelloVersion = tls_record:lowest_protocol_version(SslOpts#ssl_options.versions), Handshake0 = ssl_handshake:init_handshake_history(), {BinMsg, ConnectionStates, Handshake} = - encode_handshake(Hello, Version, ConnectionStates0, Handshake0), + encode_handshake(Hello, HelloVersion, ConnectionStates0, Handshake0), Transport:send(Socket, BinMsg), State1 = State0#state{connection_states = ConnectionStates, negotiated_version = Version, %% Requested version diff --git a/lib/ssl/src/tls_record.erl b/lib/ssl/src/tls_record.erl index aa524f0225..1e266ed424 100644 --- a/lib/ssl/src/tls_record.erl +++ b/lib/ssl/src/tls_record.erl @@ -41,8 +41,9 @@ -export([encode_plain_text/4]). %% Protocol version handling --export([protocol_version/1, lowest_protocol_version/2, - highest_protocol_version/1, is_higher/2, supported_protocol_versions/0, +-export([protocol_version/1, lowest_protocol_version/1, lowest_protocol_version/2, + highest_protocol_version/1, highest_protocol_version/2, + is_higher/2, supported_protocol_versions/0, is_acceptable_version/1, is_acceptable_version/2]). -export_type([tls_version/0, tls_atom_version/0]). @@ -257,6 +258,18 @@ lowest_protocol_version(Version = {M,_}, Version; lowest_protocol_version(_,Version) -> Version. + +%%-------------------------------------------------------------------- +-spec lowest_protocol_version([tls_version()]) -> tls_version(). +%% +%% Description: Lowest protocol version present in a list +%%-------------------------------------------------------------------- +lowest_protocol_version([]) -> + lowest_protocol_version(); +lowest_protocol_version(Versions) -> + [Ver | Vers] = Versions, + lowest_list_protocol_version(Ver, Vers). + %%-------------------------------------------------------------------- -spec highest_protocol_version([tls_version()]) -> tls_version(). %% @@ -266,19 +279,29 @@ highest_protocol_version([]) -> highest_protocol_version(); highest_protocol_version(Versions) -> [Ver | Vers] = Versions, - highest_protocol_version(Ver, Vers). + highest_list_protocol_version(Ver, Vers). -highest_protocol_version(Version, []) -> +%%-------------------------------------------------------------------- +-spec highest_protocol_version(tls_version(), tls_version()) -> tls_version(). +%% +%% Description: Highest protocol version of two given versions +%%-------------------------------------------------------------------- +highest_protocol_version(Version = {M, N}, {M, O}) when N > O -> + Version; +highest_protocol_version({M, _}, + Version = {M, _}) -> Version; -highest_protocol_version(Version = {N, M}, [{N, O} | Rest]) when M > O -> - highest_protocol_version(Version, Rest); -highest_protocol_version({M, _}, [Version = {M, _} | Rest]) -> - highest_protocol_version(Version, Rest); -highest_protocol_version(Version = {M,_}, [{N,_} | Rest]) when M > N -> - highest_protocol_version(Version, Rest); -highest_protocol_version(_, [Version | Rest]) -> - highest_protocol_version(Version, Rest). +highest_protocol_version(Version = {M,_}, + {N, _}) when M > N -> + Version; +highest_protocol_version(_,Version) -> + Version. +%%-------------------------------------------------------------------- +-spec is_higher(V1 :: tls_version(), V2::tls_version()) -> tls_version(). +%% +%% Description: Is V1 > V2 +%%-------------------------------------------------------------------- is_higher({M, N}, {M, O}) when N > O -> true; is_higher({M, _}, {N, _}) when M > N -> @@ -352,6 +375,17 @@ is_acceptable_version(_,_) -> %%-------------------------------------------------------------------- %%% Internal functions %%-------------------------------------------------------------------- + +lowest_list_protocol_version(Ver, []) -> + Ver; +lowest_list_protocol_version(Ver1, [Ver2 | Rest]) -> + lowest_list_protocol_version(lowest_protocol_version(Ver1, Ver2), Rest). + +highest_list_protocol_version(Ver, []) -> + Ver; +highest_list_protocol_version(Ver1, [Ver2 | Rest]) -> + highest_list_protocol_version(highest_protocol_version(Ver1, Ver2), Rest). + encode_tls_cipher_text(Type, {MajVer, MinVer}, Fragment) -> Length = erlang:iolist_size(Fragment), [<<?BYTE(Type), ?BYTE(MajVer), ?BYTE(MinVer), ?UINT16(Length)>>, Fragment]. @@ -370,6 +404,10 @@ mac_hash({3, N} = Version, MacAlg, MacSecret, SeqNo, Type, Length, Fragment) highest_protocol_version() -> highest_protocol_version(supported_protocol_versions()). +lowest_protocol_version() -> + lowest_protocol_version(supported_protocol_versions()). + + sufficient_tlsv1_2_crypto_support() -> CryptoSupport = crypto:supports(), proplists:get_bool(sha256, proplists:get_value(hashs, CryptoSupport)). diff --git a/lib/ssl/test/ssl_basic_SUITE.erl b/lib/ssl/test/ssl_basic_SUITE.erl index 6f6107de2c..f032c769e2 100644 --- a/lib/ssl/test/ssl_basic_SUITE.erl +++ b/lib/ssl/test/ssl_basic_SUITE.erl @@ -35,7 +35,6 @@ -include("tls_record.hrl"). -include("tls_handshake.hrl"). --define('24H_in_sec', 86400). -define(TIMEOUT, 20000). -define(EXPIRE, 10). -define(SLEEP, 500). diff --git a/lib/ssl/test/ssl_dist_SUITE.erl b/lib/ssl/test/ssl_dist_SUITE.erl index 72d62b29a7..092015d3d8 100644 --- a/lib/ssl/test/ssl_dist_SUITE.erl +++ b/lib/ssl/test/ssl_dist_SUITE.erl @@ -40,7 +40,8 @@ %% Common Test interface functions ----------------------------------- %%-------------------------------------------------------------------- all() -> - [basic, payload, plain_options, plain_verify_options]. + [basic, payload, plain_options, plain_verify_options, nodelay_option, + listen_port_options, listen_options, use_interface]. groups() -> []. @@ -250,6 +251,146 @@ plain_verify_options(Config) when is_list(Config) -> stop_ssl_node(NH1), stop_ssl_node(NH2), success(Config). +%%-------------------------------------------------------------------- +nodelay_option() -> + [{doc,"Test specifying dist_nodelay option"}]. +nodelay_option(Config) -> + try + %% The default is 'true', so try setting it to 'false'. + application:set_env(kernel, dist_nodelay, false), + basic(Config) + after + application:unset_env(kernel, dist_nodelay) + end. + +listen_port_options() -> + [{doc, "Test specifying listening ports"}]. +listen_port_options(Config) when is_list(Config) -> + %% Start a node, and get the port number it's listening on. + NH1 = start_ssl_node(Config), + Node1 = NH1#node_handle.nodename, + Name1 = lists:takewhile(fun(C) -> C =/= $@ end, atom_to_list(Node1)), + {ok, NodesPorts} = apply_on_ssl_node(NH1, fun net_adm:names/0), + {Name1, Port1} = lists:keyfind(Name1, 1, NodesPorts), + + %% Now start a second node, configuring it to use the same port + %% number. + PortOpt1 = "-kernel inet_dist_listen_min " ++ integer_to_list(Port1) ++ + " inet_dist_listen_max " ++ integer_to_list(Port1), + + try start_ssl_node([{additional_dist_opts, PortOpt1} | Config]) of + #node_handle{} -> + %% If the node was able to start, it didn't take the port + %% option into account. + exit(unexpected_success) + catch + exit:{accept_failed, timeout} -> + %% The node failed to start, as expected. + ok + end, + + %% Try again, now specifying a high max port. + PortOpt2 = "-kernel inet_dist_listen_min " ++ integer_to_list(Port1) ++ + " inet_dist_listen_max 65535", + NH2 = start_ssl_node([{additional_dist_opts, PortOpt2} | Config]), + Node2 = NH2#node_handle.nodename, + Name2 = lists:takewhile(fun(C) -> C =/= $@ end, atom_to_list(Node2)), + {ok, NodesPorts2} = apply_on_ssl_node(NH2, fun net_adm:names/0), + {Name2, Port2} = lists:keyfind(Name2, 1, NodesPorts2), + + %% The new port should be higher: + if Port2 > Port1 -> + ok; + true -> + error({port, Port2, not_higher_than, Port1}) + end, + + stop_ssl_node(NH1), + stop_ssl_node(NH2), + success(Config). +%%-------------------------------------------------------------------- +listen_options() -> + [{doc, "Test inet_dist_listen_options"}]. +listen_options(Config) when is_list(Config) -> + Prio = 1, + case gen_udp:open(0, [{priority,Prio}]) of + {ok,Socket} -> + case inet:getopts(Socket, [priority]) of + {ok,[{priority,Prio}]} -> + ok = gen_udp:close(Socket), + do_listen_options(Prio, Config); + _ -> + ok = gen_udp:close(Socket), + {skip, + "Can not set priority "++integer_to_list(Prio)++ + " on socket"} + end; + {error,_} -> + {skip, "Can not set priority on socket"} + end. + +do_listen_options(Prio, Config) -> + PriorityString0 = "[{priority,"++integer_to_list(Prio)++"}]", + PriorityString = + case os:cmd("echo [{a,1}]") of + "[{a,1}]"++_ -> + PriorityString0; + _ -> + %% Some shells need quoting of [{}] + "'"++PriorityString0++"'" + end, + + Options = "-kernel inet_dist_listen_options " ++ PriorityString, + + NH1 = start_ssl_node([{additional_dist_opts, Options} | Config]), + NH2 = start_ssl_node([{additional_dist_opts, Options} | Config]), + Node2 = NH2#node_handle.nodename, + + pong = apply_on_ssl_node(NH1, fun () -> net_adm:ping(Node2) end), + + PrioritiesNode1 = + apply_on_ssl_node(NH1, fun get_socket_priorities/0), + PrioritiesNode2 = + apply_on_ssl_node(NH2, fun get_socket_priorities/0), + + Elevated1 = [P || P <- PrioritiesNode1, P =:= Prio], + ?t:format("Elevated1: ~p~n", [Elevated1]), + Elevated2 = [P || P <- PrioritiesNode2, P =:= Prio], + ?t:format("Elevated2: ~p~n", [Elevated2]), + [_|_] = Elevated1, + [_|_] = Elevated2, + + stop_ssl_node(NH1), + stop_ssl_node(NH2), + success(Config). +%%-------------------------------------------------------------------- +use_interface() -> + [{doc, "Test inet_dist_use_interface"}]. +use_interface(Config) when is_list(Config) -> + %% Force the node to listen only on the loopback interface. + IpString = "'{127,0,0,1}'", + Options = "-kernel inet_dist_use_interface " ++ IpString, + + %% Start a node, and get the port number it's listening on. + NH1 = start_ssl_node([{additional_dist_opts, Options} | Config]), + Node1 = NH1#node_handle.nodename, + Name = lists:takewhile(fun(C) -> C =/= $@ end, atom_to_list(Node1)), + {ok, NodesPorts} = apply_on_ssl_node(NH1, fun net_adm:names/0), + {Name, Port} = lists:keyfind(Name, 1, NodesPorts), + + %% Now find the socket listening on that port, and check its sockname. + Sockets = apply_on_ssl_node( + NH1, + fun() -> + [inet:sockname(P) || + P <- erlang:ports(), + {ok, Port} =:= (catch inet:port(P))] + end), + %% And check that it's actually listening on localhost. + [{ok,{{127,0,0,1},Port}}] = Sockets, + + stop_ssl_node(NH1), + success(Config). %%-------------------------------------------------------------------- %%% Internal functions ----------------------------------------------- @@ -264,6 +405,12 @@ tstsrvr_format(Fmt, ArgList) -> send_to_tstcntrl(Message) -> send_to_tstsrvr({message, Message}). +get_socket_priorities() -> + [Priority || + {ok,[{priority,Priority}]} <- + [inet:getopts(Port, [priority]) || + Port <- erlang:ports(), + element(2, erlang:port_info(Port, name)) =:= "tcp_inet"]]. %% %% test_server side api diff --git a/lib/ssl/test/ssl_session_cache_SUITE.erl b/lib/ssl/test/ssl_session_cache_SUITE.erl index 924898f6fa..85345c814f 100644 --- a/lib/ssl/test/ssl_session_cache_SUITE.erl +++ b/lib/ssl/test/ssl_session_cache_SUITE.erl @@ -31,6 +31,7 @@ -define(SLEEP, 500). -define(TIMEOUT, 60000). -define(LONG_TIMEOUT, 600000). +-define(MAX_TABLE_SIZE, 5). -behaviour(ssl_session_cache_api). @@ -46,7 +47,9 @@ all() -> [session_cleanup, session_cache_process_list, session_cache_process_mnesia, - client_unique_session]. + client_unique_session, + max_table_size + ]. groups() -> []. @@ -92,7 +95,17 @@ init_per_testcase(session_cleanup, Config) -> Config; init_per_testcase(client_unique_session, Config) -> - ct:timetrap({seconds, 20}), + ct:timetrap({seconds, 40}), + Config; + +init_per_testcase(max_table_size, Config) -> + ssl:stop(), + application:load(ssl), + application:set_env(ssl, session_cache_server_max, ?MAX_TABLE_SIZE), + application:set_env(ssl, session_cache_client_max, ?MAX_TABLE_SIZE), + application:set_env(ssl, session_delay_cleanup_time, ?DELAY), + ssl:start(), + ct:timetrap({seconds, 40}), Config. init_customized_session_cache(Type, Config) -> @@ -122,6 +135,10 @@ end_per_testcase(session_cleanup, Config) -> application:unset_env(ssl, session_delay_cleanup_time), application:unset_env(ssl, session_lifetime), end_per_testcase(default_action, Config); +end_per_testcase(max_table_size, Config) -> + application:unset_env(ssl, session_cach_server_max), + application:unset_env(ssl, session_cach_client_max), + end_per_testcase(default_action, Config); end_per_testcase(Case, Config) when Case == session_cache_process_list; Case == session_cache_process_mnesia -> ets:delete(ssl_test), @@ -148,7 +165,7 @@ client_unique_session(Config) when is_list(Config) -> {options, ServerOpts}]), Port = ssl_test_lib:inet_port(Server), LastClient = clients_start(Server, - ClientNode, Hostname, Port, ClientOpts, 20), + ClientNode, Hostname, Port, ClientOpts, client_unique_session, 20), receive {LastClient, {ok, _}} -> ok @@ -157,7 +174,8 @@ client_unique_session(Config) when is_list(Config) -> [_, _,_, _, Prop] = StatusInfo, State = ssl_test_lib:state(Prop), ClientCache = element(2, State), - 1 = ets:info(ClientCache, size), + + 1 = ssl_session_cache:size(ClientCache), ssl_test_lib:close(Server, 500), ssl_test_lib:close(LastClient). @@ -223,35 +241,7 @@ session_cleanup(Config) when is_list(Config) -> ssl_test_lib:close(Server), ssl_test_lib:close(Client). -check_timer(Timer) -> - case erlang:read_timer(Timer) of - false -> - {status, _, _, _} = sys:get_status(whereis(ssl_manager)), - timer:sleep(?SLEEP), - {status, _, _, _} = sys:get_status(whereis(ssl_manager)), - ok; - Int -> - ct:sleep(Int), - check_timer(Timer) - end. -get_delay_timers() -> - {status, _, _, StatusInfo} = sys:get_status(whereis(ssl_manager)), - [_, _,_, _, Prop] = StatusInfo, - State = ssl_test_lib:state(Prop), - case element(8, State) of - {undefined, undefined} -> - ct:sleep(?SLEEP), - get_delay_timers(); - {undefined, _} -> - ct:sleep(?SLEEP), - get_delay_timers(); - {_, undefined} -> - ct:sleep(?SLEEP), - get_delay_timers(); - DelayTimers -> - DelayTimers - end. %%-------------------------------------------------------------------- session_cache_process_list() -> [{doc,"Test reuse of sessions (short handshake)"}]. @@ -264,6 +254,42 @@ session_cache_process_mnesia(Config) when is_list(Config) -> session_cache_process(mnesia,Config). %%-------------------------------------------------------------------- + +max_table_size() -> + [{doc,"Test max limit on session table"}]. +max_table_size(Config) when is_list(Config) -> + process_flag(trap_exit, true), + ClientOpts = ?config(client_verification_opts, Config), + ServerOpts = ?config(server_verification_opts, Config), + {ClientNode, ServerNode, Hostname} = ssl_test_lib:run_where(Config), + Server = + ssl_test_lib:start_server([{node, ServerNode}, {port, 0}, + {from, self()}, + {mfa, {ssl_test_lib, no_result, []}}, + {tcp_options, [{active, false}]}, + {options, ServerOpts}]), + Port = ssl_test_lib:inet_port(Server), + LastClient = clients_start(Server, + ClientNode, Hostname, Port, ClientOpts, max_table_size, 20), + receive + {LastClient, {ok, _}} -> + ok + end, + ct:sleep(1000), + {status, _, _, StatusInfo} = sys:get_status(whereis(ssl_manager)), + [_, _,_, _, Prop] = StatusInfo, + State = ssl_test_lib:state(Prop), + ClientCache = element(2, State), + ServerCache = element(3, State), + N = ssl_session_cache:size(ServerCache), + M = ssl_session_cache:size(ClientCache), + ct:pal("~p",[{N, M}]), + ssl_test_lib:close(Server, 500), + ssl_test_lib:close(LastClient), + true = N =< ?MAX_TABLE_SIZE, + true = M =< ?MAX_TABLE_SIZE. + +%%-------------------------------------------------------------------- %%% Session cache API callbacks %%-------------------------------------------------------------------- @@ -403,21 +429,73 @@ session_cache_process(_Type,Config) when is_list(Config) -> ssl_basic_SUITE:reuse_session(Config). -clients_start(_Server, ClientNode, Hostname, Port, ClientOpts, 0) -> +clients_start(_Server, ClientNode, Hostname, Port, ClientOpts, Test, 0) -> %% Make sure session is registered ct:sleep(?SLEEP * 2), ssl_test_lib:start_client([{node, ClientNode}, {port, Port}, {host, Hostname}, {mfa, {?MODULE, connection_info_result, []}}, - {from, self()}, {options, ClientOpts}]); -clients_start(Server, ClientNode, Hostname, Port, ClientOpts, N) -> + {from, self()}, {options, test_copts(Test, 0, ClientOpts)}]); +clients_start(Server, ClientNode, Hostname, Port, ClientOpts, Test, N) -> spawn_link(ssl_test_lib, start_client, [[{node, ClientNode}, {port, Port}, {host, Hostname}, {mfa, {ssl_test_lib, no_result, []}}, - {from, self()}, {options, ClientOpts}]]), + {from, self()}, {options, test_copts(Test, N, ClientOpts)}]]), Server ! listen, - clients_start(Server, ClientNode, Hostname, Port, ClientOpts, N-1). + wait_for_server(), + clients_start(Server, ClientNode, Hostname, Port, ClientOpts, Test, N-1). connection_info_result(Socket) -> ssl:connection_information(Socket, [protocol, cipher_suite]). + +check_timer(Timer) -> + case erlang:read_timer(Timer) of + false -> + {status, _, _, _} = sys:get_status(whereis(ssl_manager)), + timer:sleep(?SLEEP), + {status, _, _, _} = sys:get_status(whereis(ssl_manager)), + ok; + Int -> + ct:sleep(Int), + check_timer(Timer) + end. + +get_delay_timers() -> + {status, _, _, StatusInfo} = sys:get_status(whereis(ssl_manager)), + [_, _,_, _, Prop] = StatusInfo, + State = ssl_test_lib:state(Prop), + case element(8, State) of + {undefined, undefined} -> + ct:sleep(?SLEEP), + get_delay_timers(); + {undefined, _} -> + ct:sleep(?SLEEP), + get_delay_timers(); + {_, undefined} -> + ct:sleep(?SLEEP), + get_delay_timers(); + DelayTimers -> + DelayTimers + end. + +wait_for_server() -> + ct:sleep(100). + + +test_copts(_, 0, ClientOpts) -> + ClientOpts; +test_copts(max_table_size, N, ClientOpts) -> + Version = tls_record:highest_protocol_version([]), + CipherSuites = %%lists:map(fun(X) -> ssl_cipher:suite_definition(X) end, ssl_cipher:filter_suites(ssl_cipher:suites(Version))), +[ Y|| Y = {Alg,_, _, _} <- lists:map(fun(X) -> ssl_cipher:suite_definition(X) end, ssl_cipher:filter_suites(ssl_cipher:suites(Version))), Alg =/= ecdhe_ecdsa, Alg =/= ecdh_ecdsa, Alg =/= ecdh_rsa, Alg =/= ecdhe_rsa, Alg =/= dhe_dss, Alg =/= dss], + case length(CipherSuites) of + M when M >= N -> + Cipher = lists:nth(N, CipherSuites), + ct:pal("~p",[Cipher]), + [{ciphers, [Cipher]} | ClientOpts]; + _ -> + ClientOpts + end; +test_copts(_, _, ClientOpts) -> + ClientOpts. diff --git a/lib/stdlib/doc/src/rand.xml b/lib/stdlib/doc/src/rand.xml index e7d4728ef7..50057259c6 100644 --- a/lib/stdlib/doc/src/rand.xml +++ b/lib/stdlib/doc/src/rand.xml @@ -104,7 +104,7 @@ strong. If a strong cryptographic random number generator is needed, use one of functions in the <seealso marker="crypto:crypto">crypto</seealso> - module, for example <c>crypto:rand_bytes/1</c>.</p></note> + module, for example <c>crypto:strong_rand_bytes/1</c>.</p></note> </description> <datatypes> <datatype> diff --git a/lib/stdlib/doc/src/random.xml b/lib/stdlib/doc/src/random.xml index d3d7c90c31..fc4f796863 100644 --- a/lib/stdlib/doc/src/random.xml +++ b/lib/stdlib/doc/src/random.xml @@ -48,7 +48,7 @@ tuple of three integers.</p> <p>It should be noted that this random number generator is not cryptographically strong. If a strong cryptographic random number generator is needed for - example <c>crypto:rand_bytes/1</c> could be used instead.</p> + example <c>crypto:strong_rand_bytes/1</c> could be used instead.</p> <note><p>The new and improved <seealso marker="stdlib:rand">rand</seealso> module should be used instead of this module.</p></note> diff --git a/lib/stdlib/src/erl_lint.erl b/lib/stdlib/src/erl_lint.erl index c4cb5fdc80..5678e7eebe 100644 --- a/lib/stdlib/src/erl_lint.erl +++ b/lib/stdlib/src/erl_lint.erl @@ -293,6 +293,9 @@ format_error({variable_in_record_def,V}) -> %% --- binaries --- format_error({undefined_bittype,Type}) -> io_lib:format("bit type ~w undefined", [Type]); +format_error({bittype_mismatch,Val1,Val2,What}) -> + io_lib:format("conflict in ~s specification for bit field: '~p' and '~p'", + [What,Val1,Val2]); format_error(bittype_unit) -> "a bit unit size must not be specified unless a size is specified too"; format_error(illegal_bitsize) -> diff --git a/lib/stdlib/src/erl_pp.erl b/lib/stdlib/src/erl_pp.erl index f7a969977a..c5177aca90 100644 --- a/lib/stdlib/src/erl_pp.erl +++ b/lib/stdlib/src/erl_pp.erl @@ -253,6 +253,8 @@ lattribute(import, Name, _Opts, _State) when is_list(Name) -> attr("import", [{var,a0(),pname(Name)}]); lattribute(import, {From,Falist}, _Opts, _State) -> attr("import",[{var,a0(),pname(From)},falist(Falist)]); +lattribute(export_type, Talist, _Opts, _State) -> + call({var,a0(),"-export_type"}, [falist(Talist)], 0, options(none)); lattribute(optional_callbacks, Falist, Opts, _State) -> ArgL = try falist(Falist) catch _:_ -> abstract(Falist, Opts) @@ -321,7 +323,6 @@ ltype({type,_,'fun',[{type,_,any},_]}=FunType, _) -> ltype({type,_Line,'fun',[{type,_,product,_},_]}=FunType, _) -> [fun_type(['fun',$(], FunType),$)]; ltype({type,Line,T,Ts}, _) -> - %% Compatibility. Before 18.0. simple_type({atom,Line,T}, Ts); ltype({user_type,Line,T,Ts}, _) -> simple_type({atom,Line,T}, Ts); @@ -346,16 +347,8 @@ map_type(Fs) -> map_pair_types(Fs) -> tuple_type(Fs, fun map_pair_type/2). -map_pair_type({type,_Line,map_field_assoc,[Ktype,Vtype]}, Prec) -> - map_assoc_typed(ltype(Ktype), Vtype, Prec). - -map_assoc_typed(B, {type,_,union,Ts}, Prec) -> - {first,[B,$\s],{seq,[],[],[],map_assoc_union_type(Ts, Prec)}}; -map_assoc_typed(B, Type, Prec) -> - {list,[{cstep,[B," =>"],ltype(Type, Prec)}]}. - -map_assoc_union_type([T|Ts], Prec) -> - [[leaf("=> "),ltype(T)] | ltypes(Ts, fun union_elem/2, Prec)]. +map_pair_type({type,_Line,map_field_assoc,[KType,VType]}, Prec) -> + {list,[{cstep,[ltype(KType, Prec),leaf(" =>")],ltype(VType, Prec)}]}. record_type(Name, Fields) -> {first,[record_name(Name)],field_types(Fields)}. @@ -370,9 +363,6 @@ typed(B, Type) -> {_L,_P,R} = type_inop_prec('::'), {list,[{cstep,[B,' ::'],ltype(Type, R)}]}. -union_elem(T, Prec) -> - [leaf(" | "),ltype(T, Prec)]. - tuple_type(Ts, F) -> {seq,${,$},[$,],ltypes(Ts, F, 0)}. @@ -399,6 +389,9 @@ guard_type(Before, Gs) -> Gl = {list,[{step,'when',expr_list(Gs, [$,], fun constraint/2, Opts)}]}, {list,[{step,Before,Gl}]}. +constraint({type,_Line,constraint,[{atom,_,is_subtype},[{var,_,_}=V,Type]]}, + _Opts) -> + typed(lexpr(V, options(none)), Type); constraint({type,_Line,constraint,[Tag,As]}, _Opts) -> simple_type(Tag, As). diff --git a/lib/stdlib/src/rand.erl b/lib/stdlib/src/rand.erl index 8e8d0bc801..dc060e82d9 100644 --- a/lib/stdlib/src/rand.erl +++ b/lib/stdlib/src/rand.erl @@ -63,7 +63,7 @@ %% Return algorithm and seed so that RNG state can be recreated with seed/1 -spec export_seed() -> undefined | export_state(). export_seed() -> - case seed_get() of + case get(?SEED_DICT) of {#{type:=Alg}, Seed} -> {Alg, Seed}; _ -> undefined end. diff --git a/lib/stdlib/src/shell.erl b/lib/stdlib/src/shell.erl index f215a66812..ce1d9eb0ff 100644 --- a/lib/stdlib/src/shell.erl +++ b/lib/stdlib/src/shell.erl @@ -999,12 +999,7 @@ local_func(rl, [A], Bs0, _Shell, RT, Lf, Ef) -> {value,list_records(record_defs(RT, listify(Recs))),Bs}; local_func(rp, [A], Bs0, _Shell, RT, Lf, Ef) -> {[V],Bs} = expr_list([A], Bs0, Lf, Ef), - Cs = io_lib_pretty:print(V, ([{column, 1}, - {line_length, columns()}, - {depth, -1}, - {max_chars, ?CHAR_MAX}, - {record_print_fun, record_print_fun(RT)}] - ++ enc())), + Cs = pp(V, _Column=1, _Depth=-1, RT), io:requests([{put_chars, unicode, Cs}, nl]), {value,ok,Bs}; local_func(rr, [A], Bs0, _Shell, RT, Lf, Ef) -> @@ -1397,9 +1392,9 @@ get_history_and_results() -> {History, erlang:min(Results, History)}. pp(V, I, RT) -> - pp(V, I, RT, enc()). + pp(V, I, _Depth=?LINEMAX, RT). -pp(V, I, RT, Enc) -> +pp(V, I, D, RT) -> Strings = case application:get_env(stdlib, shell_strings) of {ok, false} -> @@ -1408,10 +1403,10 @@ pp(V, I, RT, Enc) -> true end, io_lib_pretty:print(V, ([{column, I}, {line_length, columns()}, - {depth, ?LINEMAX}, {max_chars, ?CHAR_MAX}, + {depth, D}, {max_chars, ?CHAR_MAX}, {strings, Strings}, {record_print_fun, record_print_fun(RT)}] - ++ Enc)). + ++ enc())). columns() -> case io:columns() of diff --git a/lib/stdlib/test/erl_lint_SUITE.erl b/lib/stdlib/test/erl_lint_SUITE.erl index 0424e2b967..5347ccaf1f 100644 --- a/lib/stdlib/test/erl_lint_SUITE.erl +++ b/lib/stdlib/test/erl_lint_SUITE.erl @@ -3604,7 +3604,10 @@ bin_syntax_errors(Config) -> t(<<X/unit:8>>) -> X; t(<<X:7/float>>) -> X; t(<< <<_:8>> >>) -> ok; - t(<<(x ! y):8/integer>>) -> ok. + t(<<(x ! y):8/integer>>) -> ok; + t(X) -> + {<<X/binary-integer>>,<<X/signed-unsigned-integer>>, + <<X/little-big>>,<<X/unit:4-unit:8>>}. ">>, [], {error,[{1,erl_lint,illegal_bitsize}, @@ -3613,7 +3616,12 @@ bin_syntax_errors(Config) -> {4,erl_lint,{undefined_bittype,bad_type}}, {5,erl_lint,bittype_unit}, {7,erl_lint,illegal_pattern}, - {8,erl_lint,illegal_pattern}], + {8,erl_lint,illegal_pattern}, + {10,erl_lint,{bittype_mismatch,integer,binary,"type"}}, + {10,erl_lint,{bittype_mismatch,unsigned,signed,"sign"}}, + {11,erl_lint,{bittype_mismatch,8,4,"unit"}}, + {11,erl_lint,{bittype_mismatch,big,little,"endianness"}} + ], [{6,erl_lint,{bad_bitsize,"float"}}]}} ], [] = run(Config, Ts), @@ -3920,22 +3928,35 @@ run_test2(Conf, Test, Warnings0) -> %% is no reason to produce an output file since we are only %% interested in the errors and warnings. - %% Print warnings, call erl_lint:format_error/1. + %% Print warnings, call erl_lint:format_error/1. (But note that + %% the compiler will ignore failing calls to erl_lint:format_error/1.) compile:file(File, [binary,report|Opts]), case compile:file(File, [binary|Opts]) of - {ok, _M, Code, Ws} when is_binary(Code) -> warnings(File, Ws); - {error, [{File,Es}], []} -> {errors, Es, []}; - {error, [{File,Es}], [{File,Ws}]} -> {error, Es, Ws}; - {error, [{File,Es1},{File,Es2}], []} -> {errors2, Es1, Es2} + {ok, _M, Code, Ws} when is_binary(Code) -> + warnings(File, Ws); + {error, [{File,Es}], []} -> + {errors, call_format_error(Es), []}; + {error, [{File,Es}], [{File,Ws}]} -> + {error, call_format_error(Es), call_format_error(Ws)}; + {error, [{File,Es1},{File,Es2}], []} -> + {errors2, Es1, Es2} end. warnings(File, Ws) -> case lists:append([W || {F, W} <- Ws, F =:= File]) of - [] -> []; - L -> {warnings, L} + [] -> + []; + L -> + {warnings, call_format_error(L)} end. +call_format_error(L) -> + %% Smoke test of format_error/1 to make sure that no crashes + %% slip through. + _ = [Mod:format_error(Term) || {_,Mod,Term} <- L], + L. + fail() -> io:format("failed~n"), ?t:fail(). diff --git a/lib/stdlib/test/erl_pp_SUITE.erl b/lib/stdlib/test/erl_pp_SUITE.erl index 389fd059f6..92e2764c65 100644 --- a/lib/stdlib/test/erl_pp_SUITE.erl +++ b/lib/stdlib/test/erl_pp_SUITE.erl @@ -960,6 +960,9 @@ maps_syntax(Config) when is_list(Config) -> "-compile(export_all).\n" "-type t1() :: map().\n" "-type t2() :: #{ atom() => integer(), atom() => float() }.\n" + "-type u() :: #{a => (I :: integer()) | (A :: atom()),\n" + " (X :: atom()) | (Y :: atom()) =>\n" + " (I :: integer()) | (A :: atom())}.\n" "-spec f1(t1()) -> 'true'.\n" "f1(M) when is_map(M) -> true.\n" "-spec f2(t2()) -> integer().\n" diff --git a/lib/stdlib/test/rand_SUITE.erl b/lib/stdlib/test/rand_SUITE.erl index 111bf620de..03b5ce1a25 100644 --- a/lib/stdlib/test/rand_SUITE.erl +++ b/lib/stdlib/test/rand_SUITE.erl @@ -126,6 +126,9 @@ seed_1(Alg) -> false = (S1 =:= rand:seed_s(Alg)), %% Negative integers works _ = rand:seed_s(Alg, {-1,-1,-1}), + %% Check that export_seed/1 returns 'undefined' if there is no seed + erase(rand_seed), + undefined = rand:export_seed(), %% Other term do not work {'EXIT', _} = (catch rand:seed_s(foobar, os:timestamp())), diff --git a/lib/wx/api_gen/gl_gen_erl.erl b/lib/wx/api_gen/gl_gen_erl.erl index 20406a8d05..84e9600bc0 100644 --- a/lib/wx/api_gen/gl_gen_erl.erl +++ b/lib/wx/api_gen/gl_gen_erl.erl @@ -226,10 +226,14 @@ gen_types(Where) -> w("-type clamp() :: float(). %% 0.0..1.0~n", []), w("-type offset() :: non_neg_integer(). %% Offset in memory block~n", []) end, - w("-type matrix() :: {float(),float(),float(),float(),~n", []), + w("-type matrix12() :: {float(),float(),float(),float(),~n", []), + w(" float(),float(),float(),float(),~n", []), + w(" float(),float(),float(),float()}.~n", []), + w("-type matrix16() :: {float(),float(),float(),float(),~n", []), w(" float(),float(),float(),float(),~n", []), w(" float(),float(),float(),float(),~n", []), w(" float(),float(),float(),float()}.~n", []), + w("-type matrix() :: matrix12() | matrix16().~n", []), w("-type mem() :: binary() | tuple(). %% Memory block~n", []), ok. @@ -480,10 +484,12 @@ doc_arg_type2(T=#type{single=true}) -> doc_arg_type3(T); doc_arg_type2(T=#type{single=undefined}) -> doc_arg_type3(T); -doc_arg_type2(T=#type{single={tuple,undefined}}) -> - "{" ++ doc_arg_type3(T) ++ "}"; +doc_arg_type2(_T=#type{single={tuple,undefined}}) -> + "tuple()"; doc_arg_type2(#type{base=float, single={tuple,16}}) -> "matrix()"; +doc_arg_type2(#type{base=string, single=list}) -> + "iolist()"; doc_arg_type2(T=#type{single={tuple,Sz}}) -> "{" ++ args(fun doc_arg_type3/1, ",", lists:duplicate(Sz,T)) ++ "}"; doc_arg_type2(T=#type{single=list}) -> diff --git a/lib/wx/api_gen/wx_extra/wxEvtHandler.c_src b/lib/wx/api_gen/wx_extra/wxEvtHandler.c_src index 5e02066309..08fef1c2ff 100644 --- a/lib/wx/api_gen/wx_extra/wxEvtHandler.c_src +++ b/lib/wx/api_gen/wx_extra/wxEvtHandler.c_src @@ -42,11 +42,15 @@ case 101: { // wxEvtHandler::Disconnect int eventType = wxeEventTypeFromAtom(bp); bp += *eventTypeLen; if(eventType > 0) { + if(recurse_level > 1) { + delayed_delete->Append(Ecmd.Save()); + } else { bool Result = This->Disconnect((int) *winid,(int) *lastId,eventType, (wxObjectEventFunction)(wxEventFunction) &wxeEvtListener::forward, NULL, Listener); rt.addBool(Result); + } } else { rt.addAtom("badarg"); rt.addAtom("event_type"); diff --git a/lib/wx/api_gen/wx_gen_cpp.erl b/lib/wx/api_gen/wx_gen_cpp.erl index 5649336b5d..ed7b27f3bf 100644 --- a/lib/wx/api_gen/wx_gen_cpp.erl +++ b/lib/wx/api_gen/wx_gen_cpp.erl @@ -1141,6 +1141,7 @@ gen_macros() -> w("#include <wx/html/htmlcell.h>~n"), w("#include <wx/filename.h>~n"), w("#include <wx/sysopt.h>~n"), + w("#include <wx/overlay.h>~n"), w("~n~n", []), w("#ifndef wxICON_DEFAULT_BITMAP_TYPE~n",[]), @@ -1276,6 +1277,11 @@ encode_events(Evs) -> w(" } else {~n"), w(" send_res = rt.send();~n"), w(" if(cb->skip) event->Skip();~n"), + w(" if(app->recurse_level < 1) {~n"), + w(" app->recurse_level++;~n"), + w(" app->dispatch_cmds();~n"), + w(" app->recurse_level--;~n"), + w(" }~n"), w(" };~n"), w(" return send_res;~n"), w(" }~n"). diff --git a/lib/wx/api_gen/wxapi.conf b/lib/wx/api_gen/wxapi.conf index f076323bea..eabbec3297 100644 --- a/lib/wx/api_gen/wxapi.conf +++ b/lib/wx/api_gen/wxapi.conf @@ -367,7 +367,7 @@ {class,wxMirrorDC, wxDC, [], ['wxMirrorDC', '~wxMirrorDC']}. {class,wxScreenDC, wxDC, [], ['wxScreenDC', '~wxScreenDC']}. -{class,wxPostScriptDC,wxDC,[], +{class,wxPostScriptDC,wxDC,[{ifdef, wxUSE_POSTSCRIPT}], ['wxPostScriptDC','~wxPostScriptDC', {'SetResolution', [{deprecated, "!wxCHECK_VERSION(2,9,0)"}]}, {'GetResolution', [{deprecated, "!wxCHECK_VERSION(2,9,0)"}]}]}. @@ -1975,3 +1975,9 @@ {class, wxMouseCaptureLostEvent, wxEvent, [{event,[wxEVT_MOUSE_CAPTURE_LOST]}],[]}. + +{class, wxOverlay, root, [], + ['wxOverlay', '~wxOverlay', 'Reset']}. + +{class, wxDCOverlay, root, [], + ['wxDCOverlay', '~wxDCOverlay', 'Clear']}. diff --git a/lib/wx/c_src/gen/wxe_derived_dest.h b/lib/wx/c_src/gen/wxe_derived_dest.h index 03d1502c2a..1dcf029244 100644 --- a/lib/wx/c_src/gen/wxe_derived_dest.h +++ b/lib/wx/c_src/gen/wxe_derived_dest.h @@ -1,7 +1,7 @@ /* * %CopyrightBegin% * - * Copyright Ericsson AB 2008-2014. All Rights Reserved. + * Copyright Ericsson AB 2008-2015. All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -86,11 +86,13 @@ class EwxScreenDC : public wxScreenDC { EwxScreenDC() : wxScreenDC() {}; }; +#if wxUSE_POSTSCRIPT class EwxPostScriptDC : public wxPostScriptDC { public: ~EwxPostScriptDC() {((WxeApp *)wxTheApp)->clearPtr(this);}; EwxPostScriptDC(const wxPrintData& printData) : wxPostScriptDC(printData) {}; EwxPostScriptDC() : wxPostScriptDC() {}; }; +#endif // wxUSE_POSTSCRIPT class EwxWindowDC : public wxWindowDC { public: ~EwxWindowDC() {((WxeApp *)wxTheApp)->clearPtr(this);}; @@ -787,3 +789,9 @@ class EwxPopupTransientWindow : public wxPopupTransientWindow { }; #endif // wxUSE_POPUPWIN +class EwxDCOverlay : public wxDCOverlay { + public: ~EwxDCOverlay() {((WxeApp *)wxTheApp)->clearPtr(this);}; + EwxDCOverlay(wxOverlay& overlay,wxWindowDC * dc,int x,int y,int width,int height) : wxDCOverlay(overlay,dc,x,y,width,height) {}; + EwxDCOverlay(wxOverlay& overlay,wxWindowDC * dc) : wxDCOverlay(overlay,dc) {}; +}; + diff --git a/lib/wx/c_src/gen/wxe_events.cpp b/lib/wx/c_src/gen/wxe_events.cpp index a532ee985d..4affe2ba53 100644 --- a/lib/wx/c_src/gen/wxe_events.cpp +++ b/lib/wx/c_src/gen/wxe_events.cpp @@ -897,6 +897,11 @@ case 235: {// wxMouseCaptureLostEvent } else { send_res = rt.send(); if(cb->skip) event->Skip(); + if(app->recurse_level < 1) { + app->recurse_level++; + app->dispatch_cmds(); + app->recurse_level--; + } }; return send_res; } diff --git a/lib/wx/c_src/gen/wxe_funcs.cpp b/lib/wx/c_src/gen/wxe_funcs.cpp index 3211664499..4025fb1c16 100644 --- a/lib/wx/c_src/gen/wxe_funcs.cpp +++ b/lib/wx/c_src/gen/wxe_funcs.cpp @@ -113,11 +113,15 @@ case 101: { // wxEvtHandler::Disconnect int eventType = wxeEventTypeFromAtom(bp); bp += *eventTypeLen; if(eventType > 0) { + if(recurse_level > 1) { + delayed_delete->Append(Ecmd.Save()); + } else { bool Result = This->Disconnect((int) *winid,(int) *lastId,eventType, (wxObjectEventFunction)(wxEventFunction) &wxeEvtListener::forward, NULL, Listener); rt.addBool(Result); + } } else { rt.addAtom("badarg"); rt.addAtom("event_type"); @@ -5856,6 +5860,7 @@ case wxScreenDC_new: { // wxScreenDC::wxScreenDC rt.addRef(getRef((void *)Result,memenv), "wxScreenDC"); break; } +#if wxUSE_POSTSCRIPT case wxPostScriptDC_new_0: { // wxPostScriptDC::wxPostScriptDC wxPostScriptDC * Result = new EwxPostScriptDC(); newPtr((void *) Result, 4, memenv); @@ -5883,6 +5888,7 @@ case wxPostScriptDC_GetResolution: { // wxPostScriptDC::GetResolution break; } #endif +#endif // wxUSE_POSTSCRIPT #if !wxCHECK_VERSION(2,9,0) case wxWindowDC_new_0: { // wxWindowDC::wxWindowDC wxWindowDC * Result = new EwxWindowDC(); @@ -31959,6 +31965,56 @@ case wxPopupTransientWindow_Dismiss: { // wxPopupTransientWindow::Dismiss break; } #endif // wxUSE_POPUPWIN +case wxOverlay_new: { // wxOverlay::wxOverlay + wxOverlay * Result = new wxOverlay(); + newPtr((void *) Result, 236, memenv); + rt.addRef(getRef((void *)Result,memenv), "wxOverlay"); + break; +} +case wxOverlay_destruct: { // wxOverlay::~wxOverlay + wxOverlay *This = (wxOverlay *) getPtr(bp,memenv); bp += 4; + if(This) { ((WxeApp *) wxTheApp)->clearPtr((void *) This); + delete This;} + break; +} +case wxOverlay_Reset: { // wxOverlay::Reset + wxOverlay *This = (wxOverlay *) getPtr(bp,memenv); bp += 4; + if(!This) throw wxe_badarg(0); + This->Reset(); + break; +} +case wxDCOverlay_new_6: { // wxDCOverlay::wxDCOverlay + wxOverlay *overlay = (wxOverlay *) getPtr(bp,memenv); bp += 4; + wxWindowDC *dc = (wxWindowDC *) getPtr(bp,memenv); bp += 4; + int * x = (int *) bp; bp += 4; + int * y = (int *) bp; bp += 4; + int * width = (int *) bp; bp += 4; + int * height = (int *) bp; bp += 4; + wxDCOverlay * Result = new EwxDCOverlay(*overlay,dc,*x,*y,*width,*height); + newPtr((void *) Result, 237, memenv); + rt.addRef(getRef((void *)Result,memenv), "wxDCOverlay"); + break; +} +case wxDCOverlay_new_2: { // wxDCOverlay::wxDCOverlay + wxOverlay *overlay = (wxOverlay *) getPtr(bp,memenv); bp += 4; + wxWindowDC *dc = (wxWindowDC *) getPtr(bp,memenv); bp += 4; + wxDCOverlay * Result = new EwxDCOverlay(*overlay,dc); + newPtr((void *) Result, 237, memenv); + rt.addRef(getRef((void *)Result,memenv), "wxDCOverlay"); + break; +} +case wxDCOverlay_destruct: { // wxDCOverlay::~wxDCOverlay + wxDCOverlay *This = (wxDCOverlay *) getPtr(bp,memenv); bp += 4; + if(This) { ((WxeApp *) wxTheApp)->clearPtr((void *) This); + delete This;} + break; +} +case wxDCOverlay_Clear: { // wxDCOverlay::Clear + wxDCOverlay *This = (wxDCOverlay *) getPtr(bp,memenv); bp += 4; + if(!This) throw wxe_badarg(0); + This->Clear(); + break; +} default: { wxeReturn error = wxeReturn(WXE_DRV_PORT, Ecmd.caller, false); error.addAtom("_wxe_error_"); error.addInt((int) Ecmd.op); @@ -32005,6 +32061,8 @@ bool WxeApp::delete_object(void *ptr, wxeRefData *refd) { case 215: /* delete (wxBitmapDataObject *) ptr;These objects must be deleted by owner object */ break; case 227: delete (wxLogNull *) ptr; break; case 231: delete (EwxLocale *) ptr; return false; + case 236: delete (wxOverlay *) ptr; break; + case 237: delete (EwxDCOverlay *) ptr; return false; default: delete (wxObject *) ptr; return false; } return true; diff --git a/lib/wx/c_src/gen/wxe_macros.h b/lib/wx/c_src/gen/wxe_macros.h index 59f9c7054e..5f51ac5f91 100644 --- a/lib/wx/c_src/gen/wxe_macros.h +++ b/lib/wx/c_src/gen/wxe_macros.h @@ -64,6 +64,7 @@ #include <wx/html/htmlcell.h> #include <wx/filename.h> #include <wx/sysopt.h> +#include <wx/overlay.h> #ifndef wxICON_DEFAULT_BITMAP_TYPE @@ -3411,5 +3412,12 @@ #define wxPopupTransientWindow_destruct 3583 #define wxPopupTransientWindow_Popup 3584 #define wxPopupTransientWindow_Dismiss 3585 +#define wxOverlay_new 3586 +#define wxOverlay_destruct 3587 +#define wxOverlay_Reset 3588 +#define wxDCOverlay_new_6 3589 +#define wxDCOverlay_new_2 3590 +#define wxDCOverlay_destruct 3591 +#define wxDCOverlay_Clear 3592 diff --git a/lib/wx/c_src/wxe_helpers.cpp b/lib/wx/c_src/wxe_helpers.cpp index cc57374d5b..1696b8bd50 100644 --- a/lib/wx/c_src/wxe_helpers.cpp +++ b/lib/wx/c_src/wxe_helpers.cpp @@ -61,6 +61,7 @@ wxeFifo::wxeFifo(unsigned int sz) m_max = sz; m_n = 0; m_first = 0; + cb_start = 0; m_old = NULL; for(unsigned int i = 0; i < sz; i++) { m_q[i].buffer = NULL; @@ -76,15 +77,30 @@ wxeFifo::~wxeFifo() { wxeCommand * wxeFifo::Get() { unsigned int pos; - if(m_n > 0) { + do { + if(m_n <= 0) + return NULL; + pos = m_first++; m_n--; m_first %= m_max; - return &m_q[pos]; - } - return NULL; + } while(m_q[pos].op == -1); + return &m_q[pos]; +} + +wxeCommand * wxeFifo::Peek(unsigned int *i) +{ + unsigned int pos; + do { + if(*i >= m_n || m_n <= 0) + return NULL; + pos = (m_first+*i) % m_max; + (*i)++; + } while(m_q[pos].op == -1); + return &m_q[pos]; } + void wxeFifo::Add(int fc, char * cbuf,int buflen, wxe_data *sd) { unsigned int pos; @@ -140,10 +156,12 @@ void wxeFifo::Append(wxeCommand *orig) pos = (m_first + m_n) % m_max; m_n++; + curr = &m_q[pos]; + curr->op = orig->op; + if(curr->op == -1) return; curr->caller = orig->caller; curr->port = orig->port; - curr->op = orig->op; curr->len = orig->len; curr->bin[0] = orig->bin[0]; curr->bin[1] = orig->bin[1]; @@ -171,17 +189,19 @@ void wxeFifo::Realloc() wxeCommand * old = m_q; wxeCommand * queue = (wxeCommand *)driver_alloc(new_sz*sizeof(wxeCommand)); + // fprintf(stderr, "\r\nrealloc qsz %d\r\n", new_sz);fflush(stderr); + m_max=new_sz; m_first = 0; m_n=0; m_q = queue; for(i=0; i < n; i++) { - unsigned int pos = i+first; - if(old[pos%max].op >= 0) { - Append(&old[pos%max]); - } + unsigned int pos = (i+first)%max; + if(old[pos].op >= 0) + Append(&old[pos]); } + for(i = m_n; i < new_sz; i++) { // Reset the rest m_q[i].buffer = NULL; m_q[i].op = -1; @@ -190,6 +210,26 @@ void wxeFifo::Realloc() m_old = old; } +// Strip end of queue if ops are already taken care of, avoids reallocs +void wxeFifo::Strip() +{ + while((m_n > 0) && (m_q[(m_first + m_n - 1)%m_max].op == -1)) { + m_n--; + } +} + +unsigned int wxeFifo::Cleanup(unsigned int def) +{ + if(m_old) { + driver_free(m_old); + m_old = NULL; + // Realloced we need to start from the beginning + return 0; + } else { + return def; + } +} + /* **************************************************************************** * TreeItemData * ****************************************************************************/ diff --git a/lib/wx/c_src/wxe_helpers.h b/lib/wx/c_src/wxe_helpers.h index 4f9d9ca9c3..ff949e332b 100644 --- a/lib/wx/c_src/wxe_helpers.h +++ b/lib/wx/c_src/wxe_helpers.h @@ -67,9 +67,13 @@ class wxeFifo { void Append(wxeCommand *Other); wxeCommand * Get(); + wxeCommand * Peek(unsigned int *item); void Realloc(); + void Strip(); + unsigned int Cleanup(unsigned int peek=0); + unsigned int cb_start; unsigned int m_max; unsigned int m_first; unsigned int m_n; diff --git a/lib/wx/c_src/wxe_impl.cpp b/lib/wx/c_src/wxe_impl.cpp index 5b34f08704..c5bad41573 100644 --- a/lib/wx/c_src/wxe_impl.cpp +++ b/lib/wx/c_src/wxe_impl.cpp @@ -57,10 +57,8 @@ extern ErlDrvTermData init_caller; extern int wxe_status; wxeFifo * wxe_queue = NULL; -wxeFifo * wxe_queue_cb_saved = NULL; unsigned int wxe_needs_signal = 0; // inside batch if larger than 0 -unsigned int wxe_cb_invoked = 0; /* ************************************************************ * Commands from erlang @@ -123,11 +121,10 @@ bool WxeApp::OnInit() { global_me = new wxeMemEnv(); - wxe_queue = new wxeFifo(1000); - wxe_queue_cb_saved = new wxeFifo(200); + wxe_queue = new wxeFifo(2000); cb_buff = NULL; recurse_level = 0; - delayed_delete = new wxeFifo(10); + delayed_delete = new wxeFifo(100); delayed_cleanup = new wxList; wxe_ps_init2(); @@ -173,7 +170,6 @@ void WxeApp::shutdown(wxeMetaCommand& Ecmd) { wxe_status = WXE_EXITING; ExitMainLoop(); delete wxe_queue; - delete wxe_queue_cb_saved; } void WxeApp::dummy_close(wxEvent& Ev) { @@ -229,12 +225,11 @@ void handle_event_callback(ErlDrvPort port, ErlDrvTermData process) if(driver_monitor_process(port, process, &monitor) == 0) { // Should we be able to handle commands when recursing? probably // fprintf(stderr, "\r\nCB EV Start %lu \r\n", process);fflush(stderr); - app->recurse_level++; - app->dispatch_cb(wxe_queue, wxe_queue_cb_saved, process); - app->recurse_level--; + app->recurse_level += 2; + app->dispatch_cb(wxe_queue, process); + app->recurse_level -= 2; // fprintf(stderr, "CB EV done %lu \r\n", process);fflush(stderr); driver_demonitor_process(port, &monitor); - wxe_cb_invoked = 1; } } @@ -242,16 +237,11 @@ void WxeApp::dispatch_cmds() { if(wxe_status != WXE_INITIATED) return; - do { - wxe_cb_invoked = 0; - recurse_level++; - // fprintf(stderr, "\r\ndispatch_saved 0 \r\n");fflush(stderr); - int level = dispatch(wxe_queue_cb_saved, 0, WXE_STORED); - // fprintf(stderr, "\r\ndispatch_normal %d\r\n", level);fflush(stderr); - dispatch(wxe_queue, level, WXE_NORMAL); - // fprintf(stderr, "\r\ndispatch_done \r\n");fflush(stderr); - recurse_level--; - } while(wxe_cb_invoked); + recurse_level++; + // fprintf(stderr, "\r\ndispatch_normal %d\r\n", level);fflush(stderr); + dispatch(wxe_queue); + // fprintf(stderr, "\r\ndispatch_done \r\n");fflush(stderr); + recurse_level--; // Cleanup old memenv's and deleted objects if(recurse_level == 0) { @@ -260,6 +250,7 @@ void WxeApp::dispatch_cmds() wxe_dispatch(*curr); curr->Delete(); } + delayed_delete->Cleanup(); if(delayed_cleanup->size() > 0) for( wxList::compatibility_iterator node = delayed_cleanup->GetFirst(); node; @@ -269,28 +260,19 @@ void WxeApp::dispatch_cmds() destroyMemEnv(*event); delete event; } - if(wxe_queue_cb_saved->m_old) { - driver_free(wxe_queue_cb_saved->m_old); - wxe_queue_cb_saved->m_old = NULL; - } - if(delayed_delete->m_old) { - driver_free(delayed_delete->m_old); - delayed_delete->m_old = NULL; - } } } -int WxeApp::dispatch(wxeFifo * batch, int blevel, int list_type) +int WxeApp::dispatch(wxeFifo * batch) { int ping = 0; + int blevel = 0; wxeCommand *event; - if(list_type == WXE_NORMAL) erl_drv_mutex_lock(wxe_batch_locker_m); + erl_drv_mutex_lock(wxe_batch_locker_m); while(true) { while((event = batch->Get()) != NULL) { - if(list_type == WXE_NORMAL) erl_drv_mutex_unlock(wxe_batch_locker_m); + erl_drv_mutex_unlock(wxe_batch_locker_m); switch(event->op) { - case -1: - break; case WXE_BATCH_END: {--blevel; } break; @@ -321,20 +303,10 @@ int WxeApp::dispatch(wxeFifo * batch, int blevel, int list_type) break; } event->Delete(); - if(list_type == WXE_NORMAL) { - if(wxe_cb_invoked) - return blevel; - else - erl_drv_mutex_lock(wxe_batch_locker_m); - } + erl_drv_mutex_lock(wxe_batch_locker_m); + batch->Cleanup(); } - if(list_type == WXE_STORED) - return blevel; - if(blevel <= 0) { // list_type == WXE_NORMAL - if(wxe_queue->m_old) { - driver_free(wxe_queue->m_old); - wxe_queue->m_old = NULL; - } + if(blevel <= 0) { erl_drv_mutex_unlock(wxe_batch_locker_m); return blevel; } @@ -348,12 +320,13 @@ int WxeApp::dispatch(wxeFifo * batch, int blevel, int list_type) } } -void WxeApp::dispatch_cb(wxeFifo * batch, wxeFifo * temp, ErlDrvTermData process) { +void WxeApp::dispatch_cb(wxeFifo * batch, ErlDrvTermData process) { wxeCommand *event; + unsigned int peek; erl_drv_mutex_lock(wxe_batch_locker_m); + peek = batch->Cleanup(batch->cb_start); while(true) { - while((event = batch->Get()) != NULL) { - erl_drv_mutex_unlock(wxe_batch_locker_m); + while((event = batch->Peek(&peek)) != NULL) { wxeMemEnv *memenv = getMemEnv(event->port); // fprintf(stderr, " Ev %d %lu\r\n", event->op, event->caller); if(event->caller == process || // Callbacks from CB process only @@ -361,8 +334,8 @@ void WxeApp::dispatch_cb(wxeFifo * batch, wxeFifo * temp, ErlDrvTermData process event->op == WXE_CB_DIED || // Event callback process died // Allow connect_cb during CB i.e. msg from wxe_server. (memenv && event->caller == memenv->owner)) { + erl_drv_mutex_unlock(wxe_batch_locker_m); switch(event->op) { - case -1: case WXE_BATCH_END: case WXE_BATCH_BEGIN: case WXE_DEBUG_PING: @@ -373,52 +346,42 @@ void WxeApp::dispatch_cb(wxeFifo * batch, wxeFifo * temp, ErlDrvTermData process memcpy(cb_buff, event->buffer, event->len); } // continue case WXE_CB_DIED: + batch->cb_start = 0; event->Delete(); + erl_drv_mutex_lock(wxe_batch_locker_m); + batch->Strip(); + erl_drv_mutex_unlock(wxe_batch_locker_m); return; case WXE_CB_START: // CB start from now accept message from CB process only process = event->caller; break; default: - size_t start=temp->m_n; + batch->cb_start = peek; // In case of recursive callbacks if(event->op < OPENGL_START) { - // fprintf(stderr, " cb %d \r\n", event->op); wxe_dispatch(*event); } else { gl_dispatch(event->op,event->buffer,event->caller,event->bin); } - if(temp->m_n > start) { - erl_drv_mutex_lock(wxe_batch_locker_m); - // We have recursed dispatch_cb and messages for this - // callback may be saved on temp list move them - // to orig list - for(unsigned int i=start; i < temp->m_n; i++) { - wxeCommand *ev = &temp->m_q[(temp->m_first+i) % temp->m_max]; - if(ev->caller == process) { - batch->Append(ev); - } - } - erl_drv_mutex_unlock(wxe_batch_locker_m); - } break; } event->Delete(); - } else { - // fprintf(stderr, " save %d %lu\r\n", event->op, event->caller); - temp->Append(event); + erl_drv_mutex_lock(wxe_batch_locker_m); + peek = batch->Cleanup(peek); } - erl_drv_mutex_lock(wxe_batch_locker_m); } // sleep until something happens // fprintf(stderr, "%s:%d sleep %d %d\r\n", __FILE__, __LINE__, - // batch->m_n, temp->m_n);fflush(stderr); + // peek, batch->m_n);fflush(stderr); wxe_needs_signal = 1; - while(batch->m_n == 0) { + while(peek >= batch->m_n) { erl_drv_cond_wait(wxe_batch_locker_c, wxe_batch_locker_m); + peek = batch->Cleanup(peek); } wxe_needs_signal = 0; } } + /* Memory handling */ void WxeApp::newMemEnv(wxeMetaCommand& Ecmd) { diff --git a/lib/wx/c_src/wxe_impl.h b/lib/wx/c_src/wxe_impl.h index d6d3095a0f..fd25296c73 100644 --- a/lib/wx/c_src/wxe_impl.h +++ b/lib/wx/c_src/wxe_impl.h @@ -67,8 +67,8 @@ public: void shutdown(wxeMetaCommand& event); - int dispatch(wxeFifo *, int, int); - void dispatch_cb(wxeFifo * batch, wxeFifo * temp, ErlDrvTermData process); + int dispatch(wxeFifo *); + void dispatch_cb(wxeFifo * batch, ErlDrvTermData process); void wxe_dispatch(wxeCommand& event); diff --git a/lib/wx/examples/demo/ex_canvas.erl b/lib/wx/examples/demo/ex_canvas.erl index 1cbb96de1f..cdc783055c 100644 --- a/lib/wx/examples/demo/ex_canvas.erl +++ b/lib/wx/examples/demo/ex_canvas.erl @@ -35,7 +35,9 @@ parent, config, canvas, - bitmap + bitmap, + overlay, + pos }). start(Config) -> @@ -60,6 +62,10 @@ do_init(Config) -> wxPanel:connect(Canvas, paint, [callback]), wxPanel:connect(Canvas, size), + wxPanel:connect(Canvas, left_down), + wxPanel:connect(Canvas, left_up), + wxPanel:connect(Canvas, motion), + wxPanel:connect(Button, command_button_clicked), %% Add to sizers @@ -78,7 +84,9 @@ do_init(Config) -> Bitmap = wxBitmap:new(erlang:max(W,30),erlang:max(30,H)), {Panel, #state{parent=Panel, config=Config, - canvas = Canvas, bitmap = Bitmap}}. + canvas = Canvas, bitmap = Bitmap, + overlay = wxOverlay:new() + }}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% Sync event from callback events, paint event must be handled in callbacks @@ -127,11 +135,39 @@ handle_event(#wx{event = #wxCommand{type = command_button_clicked}}, wxBitmap:destroy(Bmp), {noreply, State}; handle_event(#wx{event = #wxSize{size={W,H}}}, - State = #state{bitmap=Prev}) -> + State = #state{bitmap=Prev, canvas=Canvas}) -> Bitmap = wxBitmap:new(W,H), - draw(State#state.canvas, Bitmap, fun(DC) -> wxDC:clear(DC) end), + draw(Canvas, Bitmap, fun(DC) -> wxDC:clear(DC) end), wxBitmap:destroy(Prev), {noreply, State#state{bitmap = Bitmap}}; + +handle_event(#wx{event = #wxMouse{type=left_down, x=X, y=Y}}, State) -> + {noreply, State#state{pos={X,Y}}}; +handle_event(#wx{event = #wxMouse{type=motion, x=X1, y=Y1}}, + #state{pos=Start, overlay=Overlay, canvas=Canvas} = State) -> + case Start of + undefined -> ignore; + {X0,Y0} -> + DC = wxClientDC:new(Canvas), + DCO = wxDCOverlay:new(Overlay, DC), + wxDCOverlay:clear(DCO), + wxDC:setPen(DC, ?wxLIGHT_GREY_PEN), + wxDC:setBrush(DC, ?wxTRANSPARENT_BRUSH), + wxDC:drawRectangle(DC, {X0,Y0, X1-X0, Y1-Y0}), + wxDCOverlay:destroy(DCO), + wxClientDC:destroy(DC) + end, + {noreply, State}; +handle_event(#wx{event = #wxMouse{type=left_up}}, + #state{overlay=Overlay, canvas=Canvas} = State) -> + DC = wxClientDC:new(Canvas), + DCO = wxDCOverlay:new(Overlay, DC), + wxDCOverlay:clear(DCO), + wxDCOverlay:destroy(DCO), + wxClientDC:destroy(DC), + wxOverlay:reset(Overlay), + {noreply, State#state{pos=undefined}}; + handle_event(Ev = #wx{}, State = #state{}) -> demo:format(State#state.config, "Got Event ~p\n", [Ev]), {noreply, State}. @@ -155,7 +191,8 @@ handle_cast(Msg, State) -> code_change(_, _, State) -> {stop, ignore, State}. -terminate(_Reason, _) -> +terminate(_Reason, #state{overlay=Overlay}) -> + wxOverlay:destroy(Overlay), ok. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% diff --git a/lib/wx/src/gen/gl.erl b/lib/wx/src/gen/gl.erl index 58cdb59aa2..bedd4e9cca 100644 --- a/lib/wx/src/gen/gl.erl +++ b/lib/wx/src/gen/gl.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2008-2013. All Rights Reserved. +%% Copyright Ericsson AB 2008-2015. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -53,10 +53,14 @@ -type enum() :: non_neg_integer(). %% See wx/include/gl.hrl -type clamp() :: float(). %% 0.0..1.0 -type offset() :: non_neg_integer(). %% Offset in memory block --type matrix() :: {float(),float(),float(),float(), +-type matrix12() :: {float(),float(),float(),float(), + float(),float(),float(),float(), + float(),float(),float(),float()}. +-type matrix16() :: {float(),float(),float(),float(), float(),float(),float(),float(), float(),float(),float(),float(), float(),float(),float(),float()}. +-type matrix() :: matrix12() | matrix16(). -type mem() :: binary() | tuple(). %% Memory block -export([clearIndex/1,clearColor/4,clear/1,indexMask/1,colorMask/4,alphaFunc/2, @@ -4289,14 +4293,14 @@ lighti(Light,Pname,Param) -> %% @doc %% See {@link lightf/3} --spec lightfv(Light, Pname, Params) -> ok when Light :: enum(),Pname :: enum(),Params :: {float()}. +-spec lightfv(Light, Pname, Params) -> ok when Light :: enum(),Pname :: enum(),Params :: tuple(). lightfv(Light,Pname,Params) -> cast(5207, <<Light:?GLenum,Pname:?GLenum,(size(Params)):?GLuint, (<< <<C:?GLfloat>> ||C <- tuple_to_list(Params)>>)/binary,0:(((1+size(Params)) rem 2)*32)>>). %% @doc %% See {@link lightf/3} --spec lightiv(Light, Pname, Params) -> ok when Light :: enum(),Pname :: enum(),Params :: {integer()}. +-spec lightiv(Light, Pname, Params) -> ok when Light :: enum(),Pname :: enum(),Params :: tuple(). lightiv(Light,Pname,Params) -> cast(5208, <<Light:?GLenum,Pname:?GLenum,(size(Params)):?GLuint, (<< <<C:?GLint>> ||C <- tuple_to_list(Params)>>)/binary,0:(((1+size(Params)) rem 2)*32)>>). @@ -4460,14 +4464,14 @@ lightModeli(Pname,Param) -> %% @doc %% See {@link lightModelf/2} --spec lightModelfv(Pname, Params) -> ok when Pname :: enum(),Params :: {float()}. +-spec lightModelfv(Pname, Params) -> ok when Pname :: enum(),Params :: tuple(). lightModelfv(Pname,Params) -> cast(5213, <<Pname:?GLenum,(size(Params)):?GLuint, (<< <<C:?GLfloat>> ||C <- tuple_to_list(Params)>>)/binary,0:(((0+size(Params)) rem 2)*32)>>). %% @doc %% See {@link lightModelf/2} --spec lightModeliv(Pname, Params) -> ok when Pname :: enum(),Params :: {integer()}. +-spec lightModeliv(Pname, Params) -> ok when Pname :: enum(),Params :: tuple(). lightModeliv(Pname,Params) -> cast(5214, <<Pname:?GLenum,(size(Params)):?GLuint, (<< <<C:?GLint>> ||C <- tuple_to_list(Params)>>)/binary,0:(((0+size(Params)) rem 2)*32)>>). @@ -4547,14 +4551,14 @@ materiali(Face,Pname,Param) -> %% @doc %% See {@link materialf/3} --spec materialfv(Face, Pname, Params) -> ok when Face :: enum(),Pname :: enum(),Params :: {float()}. +-spec materialfv(Face, Pname, Params) -> ok when Face :: enum(),Pname :: enum(),Params :: tuple(). materialfv(Face,Pname,Params) -> cast(5217, <<Face:?GLenum,Pname:?GLenum,(size(Params)):?GLuint, (<< <<C:?GLfloat>> ||C <- tuple_to_list(Params)>>)/binary,0:(((1+size(Params)) rem 2)*32)>>). %% @doc %% See {@link materialf/3} --spec materialiv(Face, Pname, Params) -> ok when Face :: enum(),Pname :: enum(),Params :: {integer()}. +-spec materialiv(Face, Pname, Params) -> ok when Face :: enum(),Pname :: enum(),Params :: tuple(). materialiv(Face,Pname,Params) -> cast(5218, <<Face:?GLenum,Pname:?GLenum,(size(Params)):?GLuint, (<< <<C:?GLint>> ||C <- tuple_to_list(Params)>>)/binary,0:(((1+size(Params)) rem 2)*32)>>). @@ -5890,21 +5894,21 @@ texGeni(Coord,Pname,Param) -> %% @doc %% See {@link texGend/3} --spec texGendv(Coord, Pname, Params) -> ok when Coord :: enum(),Pname :: enum(),Params :: {float()}. +-spec texGendv(Coord, Pname, Params) -> ok when Coord :: enum(),Pname :: enum(),Params :: tuple(). texGendv(Coord,Pname,Params) -> cast(5246, <<Coord:?GLenum,Pname:?GLenum,(size(Params)):?GLuint,0:32, (<< <<C:?GLdouble>> ||C <- tuple_to_list(Params)>>)/binary>>). %% @doc %% See {@link texGend/3} --spec texGenfv(Coord, Pname, Params) -> ok when Coord :: enum(),Pname :: enum(),Params :: {float()}. +-spec texGenfv(Coord, Pname, Params) -> ok when Coord :: enum(),Pname :: enum(),Params :: tuple(). texGenfv(Coord,Pname,Params) -> cast(5247, <<Coord:?GLenum,Pname:?GLenum,(size(Params)):?GLuint, (<< <<C:?GLfloat>> ||C <- tuple_to_list(Params)>>)/binary,0:(((1+size(Params)) rem 2)*32)>>). %% @doc %% See {@link texGend/3} --spec texGeniv(Coord, Pname, Params) -> ok when Coord :: enum(),Pname :: enum(),Params :: {integer()}. +-spec texGeniv(Coord, Pname, Params) -> ok when Coord :: enum(),Pname :: enum(),Params :: tuple(). texGeniv(Coord,Pname,Params) -> cast(5248, <<Coord:?GLenum,Pname:?GLenum,(size(Params)):?GLuint, (<< <<C:?GLint>> ||C <- tuple_to_list(Params)>>)/binary,0:(((1+size(Params)) rem 2)*32)>>). @@ -6123,14 +6127,14 @@ texEnvi(Target,Pname,Param) -> %% replacement. The default value is `?GL_FALSE'. %% %% See <a href="http://www.opengl.org/sdk/docs/man/xhtml/glTexEnv.xml">external</a> documentation. --spec texEnvfv(Target, Pname, Params) -> ok when Target :: enum(),Pname :: enum(),Params :: {float()}. +-spec texEnvfv(Target, Pname, Params) -> ok when Target :: enum(),Pname :: enum(),Params :: tuple(). texEnvfv(Target,Pname,Params) -> cast(5254, <<Target:?GLenum,Pname:?GLenum,(size(Params)):?GLuint, (<< <<C:?GLfloat>> ||C <- tuple_to_list(Params)>>)/binary,0:(((1+size(Params)) rem 2)*32)>>). %% @doc %% See {@link texEnvfv/3} --spec texEnviv(Target, Pname, Params) -> ok when Target :: enum(),Pname :: enum(),Params :: {integer()}. +-spec texEnviv(Target, Pname, Params) -> ok when Target :: enum(),Pname :: enum(),Params :: tuple(). texEnviv(Target,Pname,Params) -> cast(5255, <<Target:?GLenum,Pname:?GLenum,(size(Params)):?GLuint, (<< <<C:?GLint>> ||C <- tuple_to_list(Params)>>)/binary,0:(((1+size(Params)) rem 2)*32)>>). @@ -6455,14 +6459,14 @@ texParameteri(Target,Pname,Param) -> %% @doc %% See {@link texParameterf/3} --spec texParameterfv(Target, Pname, Params) -> ok when Target :: enum(),Pname :: enum(),Params :: {float()}. +-spec texParameterfv(Target, Pname, Params) -> ok when Target :: enum(),Pname :: enum(),Params :: tuple(). texParameterfv(Target,Pname,Params) -> cast(5260, <<Target:?GLenum,Pname:?GLenum,(size(Params)):?GLuint, (<< <<C:?GLfloat>> ||C <- tuple_to_list(Params)>>)/binary,0:(((1+size(Params)) rem 2)*32)>>). %% @doc %% See {@link texParameterf/3} --spec texParameteriv(Target, Pname, Params) -> ok when Target :: enum(),Pname :: enum(),Params :: {integer()}. +-spec texParameteriv(Target, Pname, Params) -> ok when Target :: enum(),Pname :: enum(),Params :: tuple(). texParameteriv(Target,Pname,Params) -> cast(5261, <<Target:?GLenum,Pname:?GLenum,(size(Params)):?GLuint, (<< <<C:?GLint>> ||C <- tuple_to_list(Params)>>)/binary,0:(((1+size(Params)) rem 2)*32)>>). @@ -7609,14 +7613,14 @@ fogi(Pname,Param) -> %% @doc %% See {@link fogf/2} --spec fogfv(Pname, Params) -> ok when Pname :: enum(),Params :: {float()}. +-spec fogfv(Pname, Params) -> ok when Pname :: enum(),Params :: tuple(). fogfv(Pname,Params) -> cast(5306, <<Pname:?GLenum,(size(Params)):?GLuint, (<< <<C:?GLfloat>> ||C <- tuple_to_list(Params)>>)/binary,0:(((0+size(Params)) rem 2)*32)>>). %% @doc %% See {@link fogf/2} --spec fogiv(Pname, Params) -> ok when Pname :: enum(),Params :: {integer()}. +-spec fogiv(Pname, Params) -> ok when Pname :: enum(),Params :: tuple(). fogiv(Pname,Params) -> cast(5307, <<Pname:?GLenum,(size(Params)):?GLuint, (<< <<C:?GLint>> ||C <- tuple_to_list(Params)>>)/binary,0:(((0+size(Params)) rem 2)*32)>>). @@ -8522,24 +8526,24 @@ convolutionFilter2D(Target,Internalformat,Width,Height,Format,Type,Image) -> %% image were replicated. %% %% See <a href="http://www.opengl.org/sdk/docs/man/xhtml/glConvolutionParameter.xml">external</a> documentation. --spec convolutionParameterf(Target, Pname, Params) -> ok when Target :: enum(),Pname :: enum(),Params :: {float()}. +-spec convolutionParameterf(Target, Pname, Params) -> ok when Target :: enum(),Pname :: enum(),Params :: tuple(). convolutionParameterf(Target,Pname,Params) -> cast(5339, <<Target:?GLenum,Pname:?GLenum,(size(Params)):?GLuint, (<< <<C:?GLfloat>> ||C <- tuple_to_list(Params)>>)/binary,0:(((1+size(Params)) rem 2)*32)>>). %% @equiv convolutionParameterf(Target,Pname,Params) --spec convolutionParameterfv(Target :: enum(),Pname :: enum(),Params) -> ok when Params :: {Params :: {float()}}. +-spec convolutionParameterfv(Target :: enum(),Pname :: enum(),Params) -> ok when Params :: {Params :: tuple()}. convolutionParameterfv(Target,Pname,{Params}) -> convolutionParameterf(Target,Pname,Params). %% @doc %% See {@link convolutionParameterf/3} --spec convolutionParameteri(Target, Pname, Params) -> ok when Target :: enum(),Pname :: enum(),Params :: {integer()}. +-spec convolutionParameteri(Target, Pname, Params) -> ok when Target :: enum(),Pname :: enum(),Params :: tuple(). convolutionParameteri(Target,Pname,Params) -> cast(5340, <<Target:?GLenum,Pname:?GLenum,(size(Params)):?GLuint, (<< <<C:?GLint>> ||C <- tuple_to_list(Params)>>)/binary,0:(((1+size(Params)) rem 2)*32)>>). %% @equiv convolutionParameteri(Target,Pname,Params) --spec convolutionParameteriv(Target :: enum(),Pname :: enum(),Params) -> ok when Params :: {Params :: {integer()}}. +-spec convolutionParameteriv(Target :: enum(),Pname :: enum(),Params) -> ok when Params :: {Params :: tuple()}. convolutionParameteriv(Target,Pname,{Params}) -> convolutionParameteri(Target,Pname,Params). %% @doc Copy pixels into a one-dimensional convolution filter @@ -9671,7 +9675,7 @@ pointParameterf(Pname,Param) -> %% @doc %% See {@link pointParameterf/2} --spec pointParameterfv(Pname, Params) -> ok when Pname :: enum(),Params :: {float()}. +-spec pointParameterfv(Pname, Params) -> ok when Pname :: enum(),Params :: tuple(). pointParameterfv(Pname,Params) -> cast(5397, <<Pname:?GLenum,(size(Params)):?GLuint, (<< <<C:?GLfloat>> ||C <- tuple_to_list(Params)>>)/binary,0:(((0+size(Params)) rem 2)*32)>>). @@ -9684,7 +9688,7 @@ pointParameteri(Pname,Param) -> %% @doc %% See {@link pointParameterf/2} --spec pointParameteriv(Pname, Params) -> ok when Pname :: enum(),Params :: {integer()}. +-spec pointParameteriv(Pname, Params) -> ok when Pname :: enum(),Params :: tuple(). pointParameteriv(Pname,Params) -> cast(5399, <<Pname:?GLenum,(size(Params)):?GLuint, (<< <<C:?GLint>> ||C <- tuple_to_list(Params)>>)/binary,0:(((0+size(Params)) rem 2)*32)>>). @@ -11529,7 +11533,7 @@ linkProgram(Program) -> %% scanned or parsed at this time; they are simply copied into the specified shader object. %% %% See <a href="http://www.opengl.org/sdk/docs/man/xhtml/glShaderSource.xml">external</a> documentation. --spec shaderSource(Shader, String) -> ok when Shader :: integer(),String :: [string()]. +-spec shaderSource(Shader, String) -> ok when Shader :: integer(),String :: iolist(). shaderSource(Shader,String) -> StringTemp = list_to_binary([[Str|[0]] || Str <- String ]), cast(5473, <<Shader:?GLuint,(length(String)):?GLuint,(size(StringTemp)):?GLuint,(StringTemp)/binary,0:((8-((size(StringTemp)+0) rem 8)) rem 8)>>). @@ -12278,7 +12282,7 @@ bindBufferBase(Target,Index,Buffer) -> %% and the buffer mode is `?GL_INTERLEAVED_ATTRIBS'. %% %% See <a href="http://www.opengl.org/sdk/docs/man/xhtml/glTransformFeedbackVaryings.xml">external</a> documentation. --spec transformFeedbackVaryings(Program, Varyings, BufferMode) -> ok when Program :: integer(),Varyings :: [string()],BufferMode :: enum(). +-spec transformFeedbackVaryings(Program, Varyings, BufferMode) -> ok when Program :: integer(),Varyings :: iolist(),BufferMode :: enum(). transformFeedbackVaryings(Program,Varyings,BufferMode) -> VaryingsTemp = list_to_binary([[Str|[0]] || Str <- Varyings ]), cast(5536, <<Program:?GLuint,(length(Varyings)):?GLuint,(size(VaryingsTemp)):?GLuint,(VaryingsTemp)/binary,0:((8-((size(VaryingsTemp)+0) rem 8)) rem 8),BufferMode:?GLenum>>). @@ -12596,7 +12600,7 @@ uniform4uiv(Location,Value) -> %% @doc %% See {@link texParameterf/3} --spec texParameterIiv(Target, Pname, Params) -> ok when Target :: enum(),Pname :: enum(),Params :: {integer()}. +-spec texParameterIiv(Target, Pname, Params) -> ok when Target :: enum(),Pname :: enum(),Params :: tuple(). texParameterIiv(Target,Pname,Params) -> cast(5568, <<Target:?GLenum,Pname:?GLenum,(size(Params)):?GLuint, (<< <<C:?GLint>> ||C <- tuple_to_list(Params)>>)/binary,0:(((1+size(Params)) rem 2)*32)>>). @@ -12604,7 +12608,7 @@ texParameterIiv(Target,Pname,Params) -> %% @doc glTexParameterI %% %% See <a href="http://www.opengl.org/sdk/docs/man/xhtml/glTexParameterI.xml">external</a> documentation. --spec texParameterIuiv(Target, Pname, Params) -> ok when Target :: enum(),Pname :: enum(),Params :: {integer()}. +-spec texParameterIuiv(Target, Pname, Params) -> ok when Target :: enum(),Pname :: enum(),Params :: tuple(). texParameterIuiv(Target,Pname,Params) -> cast(5569, <<Target:?GLenum,Pname:?GLenum,(size(Params)):?GLuint, (<< <<C:?GLuint>> ||C <- tuple_to_list(Params)>>)/binary,0:(((1+size(Params)) rem 2)*32)>>). @@ -12651,21 +12655,21 @@ getTexParameterIuiv(Target,Pname) -> %% and the buffer being cleared is defined. However, this is not an error. %% %% See <a href="http://www.opengl.org/sdk/docs/man/xhtml/glClearBuffer.xml">external</a> documentation. --spec clearBufferiv(Buffer, Drawbuffer, Value) -> ok when Buffer :: enum(),Drawbuffer :: integer(),Value :: {integer()}. +-spec clearBufferiv(Buffer, Drawbuffer, Value) -> ok when Buffer :: enum(),Drawbuffer :: integer(),Value :: tuple(). clearBufferiv(Buffer,Drawbuffer,Value) -> cast(5572, <<Buffer:?GLenum,Drawbuffer:?GLint,(size(Value)):?GLuint, (<< <<C:?GLint>> ||C <- tuple_to_list(Value)>>)/binary,0:(((1+size(Value)) rem 2)*32)>>). %% @doc %% See {@link clearBufferiv/3} --spec clearBufferuiv(Buffer, Drawbuffer, Value) -> ok when Buffer :: enum(),Drawbuffer :: integer(),Value :: {integer()}. +-spec clearBufferuiv(Buffer, Drawbuffer, Value) -> ok when Buffer :: enum(),Drawbuffer :: integer(),Value :: tuple(). clearBufferuiv(Buffer,Drawbuffer,Value) -> cast(5573, <<Buffer:?GLenum,Drawbuffer:?GLint,(size(Value)):?GLuint, (<< <<C:?GLuint>> ||C <- tuple_to_list(Value)>>)/binary,0:(((1+size(Value)) rem 2)*32)>>). %% @doc %% See {@link clearBufferiv/3} --spec clearBufferfv(Buffer, Drawbuffer, Value) -> ok when Buffer :: enum(),Drawbuffer :: integer(),Value :: {float()}. +-spec clearBufferfv(Buffer, Drawbuffer, Value) -> ok when Buffer :: enum(),Drawbuffer :: integer(),Value :: tuple(). clearBufferfv(Buffer,Drawbuffer,Value) -> cast(5574, <<Buffer:?GLenum,Drawbuffer:?GLint,(size(Value)):?GLuint, (<< <<C:?GLfloat>> ||C <- tuple_to_list(Value)>>)/binary,0:(((1+size(Value)) rem 2)*32)>>). @@ -13219,7 +13223,7 @@ createShaderObjectARB(ShaderType) -> %% @doc glShaderSourceARB %% %% See <a href="http://www.opengl.org/sdk/docs/man/xhtml/glShaderSourceARB.xml">external</a> documentation. --spec shaderSourceARB(ShaderObj, String) -> ok when ShaderObj :: integer(),String :: [string()]. +-spec shaderSourceARB(ShaderObj, String) -> ok when ShaderObj :: integer(),String :: iolist(). shaderSourceARB(ShaderObj,String) -> StringTemp = list_to_binary([[Str|[0]] || Str <- String ]), cast(5630, <<ShaderObj:?GLhandleARB,(length(String)):?GLuint,(size(StringTemp)):?GLuint,(StringTemp)/binary,0:((8-((size(StringTemp)+4) rem 8)) rem 8)>>). @@ -13927,7 +13931,7 @@ isVertexArray(Array) -> %% If an error occurs, nothing is written to `UniformIndices' . %% %% See <a href="http://www.opengl.org/sdk/docs/man/xhtml/glGetUniformIndices.xml">external</a> documentation. --spec getUniformIndices(Program, UniformNames) -> [integer()] when Program :: integer(),UniformNames :: [string()]. +-spec getUniformIndices(Program, UniformNames) -> [integer()] when Program :: integer(),UniformNames :: iolist(). getUniformIndices(Program,UniformNames) -> UniformNamesTemp = list_to_binary([[Str|[0]] || Str <- UniformNames ]), call(5675, <<Program:?GLuint,(length(UniformNames)):?GLuint,(size(UniformNamesTemp)):?GLuint,(UniformNamesTemp)/binary,0:((8-((size(UniformNamesTemp)+0) rem 8)) rem 8)>>). @@ -14458,7 +14462,7 @@ deleteNamedStringARB(Name) -> %% @doc glCompileShaderIncludeARB %% %% See <a href="http://www.opengl.org/sdk/docs/man/xhtml/glCompileShaderIncludeARB.xml">external</a> documentation. --spec compileShaderIncludeARB(Shader, Path) -> ok when Shader :: integer(),Path :: [string()]. +-spec compileShaderIncludeARB(Shader, Path) -> ok when Shader :: integer(),Path :: iolist(). compileShaderIncludeARB(Shader,Path) -> PathTemp = list_to_binary([[Str|[0]] || Str <- Path ]), cast(5703, <<Shader:?GLuint,(length(Path)):?GLuint,(size(PathTemp)):?GLuint,(PathTemp)/binary,0:((8-((size(PathTemp)+0) rem 8)) rem 8)>>). @@ -15617,7 +15621,7 @@ activeShaderProgram(Pipeline,Program) -> %% @doc glCreateShaderProgramv %% %% See <a href="http://www.opengl.org/sdk/docs/man/xhtml/glCreateShaderProgramv.xml">external</a> documentation. --spec createShaderProgramv(Type, Strings) -> integer() when Type :: enum(),Strings :: [string()]. +-spec createShaderProgramv(Type, Strings) -> integer() when Type :: enum(),Strings :: iolist(). createShaderProgramv(Type,Strings) -> StringsTemp = list_to_binary([[Str|[0]] || Str <- Strings ]), call(5778, <<Type:?GLenum,(length(Strings)):?GLuint,(size(StringsTemp)):?GLuint,(StringsTemp)/binary,0:((8-((size(StringsTemp)+0) rem 8)) rem 8)>>). diff --git a/lib/wx/src/gen/glu.erl b/lib/wx/src/gen/glu.erl index 6a6e20b3e4..5faba48930 100644 --- a/lib/wx/src/gen/glu.erl +++ b/lib/wx/src/gen/glu.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2008-2013. All Rights Reserved. +%% Copyright Ericsson AB 2008-2015. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -51,10 +51,14 @@ -define(GLint64,64/native-signed). -type vertex() :: {float(), float(), float()}. -type enum() :: non_neg_integer(). %% See wx/include/gl.hrl or glu.hrl --type matrix() :: {float(),float(),float(),float(), +-type matrix12() :: {float(),float(),float(),float(), + float(),float(),float(),float(), + float(),float(),float(),float()}. +-type matrix16() :: {float(),float(),float(),float(), float(),float(),float(),float(), float(),float(),float(),float(), float(),float(),float(),float()}. +-type matrix() :: matrix12() | matrix16(). -type mem() :: binary() | tuple(). %% Memory block -export([tesselate/2,build1DMipmapLevels/9,build1DMipmaps/6,build2DMipmapLevels/10, diff --git a/lib/wx/src/gen/wxDCOverlay.erl b/lib/wx/src/gen/wxDCOverlay.erl new file mode 100644 index 0000000000..f98e310ba6 --- /dev/null +++ b/lib/wx/src/gen/wxDCOverlay.erl @@ -0,0 +1,70 @@ +%% +%% %CopyrightBegin% +%% +%% Copyright Ericsson AB 2008-2015. All Rights Reserved. +%% +%% Licensed under the Apache License, Version 2.0 (the "License"); +%% you may not use this file except in compliance with the License. +%% You may obtain a copy of the License at +%% +%% http://www.apache.org/licenses/LICENSE-2.0 +%% +%% Unless required by applicable law or agreed to in writing, software +%% distributed under the License is distributed on an "AS IS" BASIS, +%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +%% See the License for the specific language governing permissions and +%% limitations under the License. +%% +%% %CopyrightEnd% +%% This file is generated DO NOT EDIT + +%% @doc See external documentation: <a href="http://www.wxwidgets.org/manuals/2.8.12/wx_wxdcoverlay.html">wxDCOverlay</a>. +%% @type wxDCOverlay(). An object reference, The representation is internal +%% and can be changed without notice. It can't be used for comparsion +%% stored on disc or distributed for use on other nodes. + +-module(wxDCOverlay). +-include("wxe.hrl"). +-export([clear/1,destroy/1,new/2,new/6]). + +%% inherited exports +-export([parent_class/1]). + +-export_type([wxDCOverlay/0]). +%% @hidden +parent_class(_Class) -> erlang:error({badtype, ?MODULE}). + +-type wxDCOverlay() :: wx:wx_object(). +%% @doc See <a href="http://www.wxwidgets.org/manuals/2.8.12/wx_wxdcoverlay.html#wxdcoverlaywxdcoverlay">external documentation</a>. +-spec new(Overlay, Dc) -> wxDCOverlay() when + Overlay::wxOverlay:wxOverlay(), Dc::wxWindowDC:wxWindowDC(). +new(#wx_ref{type=OverlayT,ref=OverlayRef},#wx_ref{type=DcT,ref=DcRef}) -> + ?CLASS(OverlayT,wxOverlay), + ?CLASS(DcT,wxWindowDC), + wxe_util:construct(?wxDCOverlay_new_2, + <<OverlayRef:32/?UI,DcRef:32/?UI>>). + +%% @doc See <a href="http://www.wxwidgets.org/manuals/2.8.12/wx_wxdcoverlay.html#wxdcoverlaywxdcoverlay">external documentation</a>. +-spec new(Overlay, Dc, X, Y, Width, Height) -> wxDCOverlay() when + Overlay::wxOverlay:wxOverlay(), Dc::wxWindowDC:wxWindowDC(), X::integer(), Y::integer(), Width::integer(), Height::integer(). +new(#wx_ref{type=OverlayT,ref=OverlayRef},#wx_ref{type=DcT,ref=DcRef},X,Y,Width,Height) + when is_integer(X),is_integer(Y),is_integer(Width),is_integer(Height) -> + ?CLASS(OverlayT,wxOverlay), + ?CLASS(DcT,wxWindowDC), + wxe_util:construct(?wxDCOverlay_new_6, + <<OverlayRef:32/?UI,DcRef:32/?UI,X:32/?UI,Y:32/?UI,Width:32/?UI,Height:32/?UI>>). + +%% @doc See <a href="http://www.wxwidgets.org/manuals/2.8.12/wx_wxdcoverlay.html#wxdcoverlayclear">external documentation</a>. +-spec clear(This) -> ok when + This::wxDCOverlay(). +clear(#wx_ref{type=ThisT,ref=ThisRef}) -> + ?CLASS(ThisT,wxDCOverlay), + wxe_util:cast(?wxDCOverlay_Clear, + <<ThisRef:32/?UI>>). + +%% @doc Destroys this object, do not use object again +-spec destroy(This::wxDCOverlay()) -> ok. +destroy(Obj=#wx_ref{type=Type}) -> + ?CLASS(Type,wxDCOverlay), + wxe_util:destroy(?wxDCOverlay_destruct,Obj), + ok. diff --git a/lib/wx/src/gen/wxOverlay.erl b/lib/wx/src/gen/wxOverlay.erl new file mode 100644 index 0000000000..7da3ece657 --- /dev/null +++ b/lib/wx/src/gen/wxOverlay.erl @@ -0,0 +1,57 @@ +%% +%% %CopyrightBegin% +%% +%% Copyright Ericsson AB 2008-2015. All Rights Reserved. +%% +%% Licensed under the Apache License, Version 2.0 (the "License"); +%% you may not use this file except in compliance with the License. +%% You may obtain a copy of the License at +%% +%% http://www.apache.org/licenses/LICENSE-2.0 +%% +%% Unless required by applicable law or agreed to in writing, software +%% distributed under the License is distributed on an "AS IS" BASIS, +%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +%% See the License for the specific language governing permissions and +%% limitations under the License. +%% +%% %CopyrightEnd% +%% This file is generated DO NOT EDIT + +%% @doc See external documentation: <a href="http://www.wxwidgets.org/manuals/2.8.12/wx_wxoverlay.html">wxOverlay</a>. +%% @type wxOverlay(). An object reference, The representation is internal +%% and can be changed without notice. It can't be used for comparsion +%% stored on disc or distributed for use on other nodes. + +-module(wxOverlay). +-include("wxe.hrl"). +-export([destroy/1,new/0,reset/1]). + +%% inherited exports +-export([parent_class/1]). + +-export_type([wxOverlay/0]). +%% @hidden +parent_class(_Class) -> erlang:error({badtype, ?MODULE}). + +-type wxOverlay() :: wx:wx_object(). +%% @doc See <a href="http://www.wxwidgets.org/manuals/2.8.12/wx_wxoverlay.html#wxoverlaywxoverlay">external documentation</a>. +-spec new() -> wxOverlay(). +new() -> + wxe_util:construct(?wxOverlay_new, + <<>>). + +%% @doc See <a href="http://www.wxwidgets.org/manuals/2.8.12/wx_wxoverlay.html#wxoverlayreset">external documentation</a>. +-spec reset(This) -> ok when + This::wxOverlay(). +reset(#wx_ref{type=ThisT,ref=ThisRef}) -> + ?CLASS(ThisT,wxOverlay), + wxe_util:cast(?wxOverlay_Reset, + <<ThisRef:32/?UI>>). + +%% @doc Destroys this object, do not use object again +-spec destroy(This::wxOverlay()) -> ok. +destroy(Obj=#wx_ref{type=Type}) -> + ?CLASS(Type,wxOverlay), + wxe_util:destroy(?wxOverlay_destruct,Obj), + ok. diff --git a/lib/wx/src/gen/wxe_debug.hrl b/lib/wx/src/gen/wxe_debug.hrl index 2cb73c0fed..6c7602acd3 100644 --- a/lib/wx/src/gen/wxe_debug.hrl +++ b/lib/wx/src/gen/wxe_debug.hrl @@ -3363,6 +3363,13 @@ wxdebug_table() -> {3583, {wxPopupTransientWindow, destruct, 0}}, {3584, {wxPopupTransientWindow, popup, 1}}, {3585, {wxPopupTransientWindow, dismiss, 0}}, + {3586, {wxOverlay, new, 0}}, + {3587, {wxOverlay, destruct, 0}}, + {3588, {wxOverlay, reset, 0}}, + {3589, {wxDCOverlay, new_6, 6}}, + {3590, {wxDCOverlay, new_2, 2}}, + {3591, {wxDCOverlay, destruct, 0}}, + {3592, {wxDCOverlay, clear, 0}}, {-1, {mod, func, -1}} ]. diff --git a/lib/wx/src/gen/wxe_funcs.hrl b/lib/wx/src/gen/wxe_funcs.hrl index d8c2ba9171..3a34cd494d 100644 --- a/lib/wx/src/gen/wxe_funcs.hrl +++ b/lib/wx/src/gen/wxe_funcs.hrl @@ -3360,3 +3360,10 @@ -define(wxPopupTransientWindow_destruct, 3583). -define(wxPopupTransientWindow_Popup, 3584). -define(wxPopupTransientWindow_Dismiss, 3585). +-define(wxOverlay_new, 3586). +-define(wxOverlay_destruct, 3587). +-define(wxOverlay_Reset, 3588). +-define(wxDCOverlay_new_6, 3589). +-define(wxDCOverlay_new_2, 3590). +-define(wxDCOverlay_destruct, 3591). +-define(wxDCOverlay_Clear, 3592). diff --git a/lib/wx/src/wxe_server.erl b/lib/wx/src/wxe_server.erl index cc253b1143..ae9440f890 100644 --- a/lib/wx/src/wxe_server.erl +++ b/lib/wx/src/wxe_server.erl @@ -352,25 +352,8 @@ handle_disconnect(Object, Evh = #evh{cb=Fun}, From, State0 = #state{users=Users0, cb=Callbacks}) -> #user{events=Evs0} = gb_trees:get(From, Users0), FunId = gb_trees:lookup(Fun, Callbacks), - case find_handler(Evs0, Object, Evh#evh{cb=FunId}) of - [] -> - {reply, false, State0}; - Handlers -> - case disconnect(Object,Handlers) of - #evh{} -> {reply, true, State0}; - Result -> {reply, Result, State0} - end - end. - -disconnect(Object,[Ev|Evs]) -> - try wxEvtHandler:disconnect_impl(Object,Ev) of - true -> Ev; - false -> disconnect(Object, Evs); - Error -> Error - catch _:_ -> - false - end; -disconnect(_, []) -> false. + Handlers = find_handler(Evs0, Object, Evh#evh{cb=FunId}), + {reply, {try_in_order, Handlers}, State0}. find_handler([{Object,Evh}|Evs], Object, Match) -> case match_handler(Match, Evh) of diff --git a/lib/wx/src/wxe_util.erl b/lib/wx/src/wxe_util.erl index 1983e6783a..398ceddd4f 100644 --- a/lib/wx/src/wxe_util.erl +++ b/lib/wx/src/wxe_util.erl @@ -127,8 +127,21 @@ connect_cb(Object,EvData0 = #evh{cb=Callback}) -> disconnect_cb(Object,EvData) -> Server = (wx:get_env())#wx_env.sv, - gen_server:call(Server, {disconnect_cb,Object,EvData}, infinity). - + {try_in_order, Handlers} = + gen_server:call(Server, {disconnect_cb,Object,EvData}, infinity), + disconnect(Object, Handlers). + +disconnect(Object,[Ev|Evs]) -> + try wxEvtHandler:disconnect_impl(Object,Ev) of + true -> true; + false -> disconnect(Object, Evs); + Error -> Error + catch _:_ -> + false + end; +disconnect(_, []) -> false. + + debug_cast(1, Op, _Args, _Port) -> check_previous(), case ets:lookup(wx_debug_info,Op) of diff --git a/make/otp_release_targets.mk b/make/otp_release_targets.mk index 97e9e4bb43..e104b68991 100644 --- a/make/otp_release_targets.mk +++ b/make/otp_release_targets.mk @@ -113,7 +113,16 @@ $(HTMLDIR)/$(APPLICATION).eix: $(XML_FILES) $(SPECS_FILES) docs: $(HTMLDIR)/$(APPLICATION).eix xmllint: $(XML_FILES) - $(XMLLINT) --noout --valid --nodefdtd --loaddtd --path $(DOCGEN)/priv/dtd:$(DOCGEN)/priv/dtd_html_entities $(XML_FILES) + @echo "Running xmllint" + @BookFiles=`awk -F\" '/xi:include/ {print $$2}' book.xml`; \ + for i in $$BookFiles; do \ + if [ $$i = "notes.xml" ]; then \ + echo Checking $$i; \ + xmllint --noout --valid --nodefdtd --loaddtd --path $(DOCGEN)/priv/dtd:$(DOCGEN)/priv/dtd_html_entities $$i; \ + else\ + awk -F\" '/xi:include/ {print "echo Checking " $$2 ;print "xmllint --noout --valid --nodefdtd --loaddtd --path $(DOCGEN)/priv/dtd:$(DOCGEN)/priv/dtd_html_entities " $$2}' $$i |sh; \ + fi \ + done # ---------------------------------------------------- # Local documentation target for testing diff --git a/otp_versions.table b/otp_versions.table index 09fe46cf57..587748895f 100644 --- a/otp_versions.table +++ b/otp_versions.table @@ -1,3 +1,4 @@ +OTP-18.1.5 : ssh-4.1.3 # asn1-4.0 common_test-1.11 compiler-6.0.1 cosEvent-2.2 cosEventDomain-1.2 cosFileTransfer-1.2 cosNotification-1.2 cosProperty-1.2 cosTime-1.2 cosTransactions-1.3 crypto-3.6.1 debugger-4.1.1 dialyzer-2.8.1 diameter-1.11 edoc-0.7.17 eldap-1.2 erl_docgen-0.4 erl_interface-3.8 erts-7.1 et-1.5.1 eunit-2.2.11 gs-1.6 hipe-3.13 ic-4.4 inets-6.0.3 jinterface-1.6 kernel-4.1 megaco-3.18 mnesia-4.13.2 observer-2.1 odbc-2.11.1 orber-3.8 os_mon-2.4 ose-1.1 otp_mibs-1.1 parsetools-2.1 percept-0.8.11 public_key-1.0.1 reltool-0.7 runtime_tools-1.9.1 sasl-2.6 snmp-5.2 ssl-7.1 stdlib-2.6 syntax_tools-1.7 test_server-3.9 tools-2.8.1 typer-0.9.9 webtool-0.9 wx-1.5 xmerl-1.3.8 : OTP-18.1.4 : inets-6.0.3 # asn1-4.0 common_test-1.11 compiler-6.0.1 cosEvent-2.2 cosEventDomain-1.2 cosFileTransfer-1.2 cosNotification-1.2 cosProperty-1.2 cosTime-1.2 cosTransactions-1.3 crypto-3.6.1 debugger-4.1.1 dialyzer-2.8.1 diameter-1.11 edoc-0.7.17 eldap-1.2 erl_docgen-0.4 erl_interface-3.8 erts-7.1 et-1.5.1 eunit-2.2.11 gs-1.6 hipe-3.13 ic-4.4 jinterface-1.6 kernel-4.1 megaco-3.18 mnesia-4.13.2 observer-2.1 odbc-2.11.1 orber-3.8 os_mon-2.4 ose-1.1 otp_mibs-1.1 parsetools-2.1 percept-0.8.11 public_key-1.0.1 reltool-0.7 runtime_tools-1.9.1 sasl-2.6 snmp-5.2 ssh-4.1.2 ssl-7.1 stdlib-2.6 syntax_tools-1.7 test_server-3.9 tools-2.8.1 typer-0.9.9 webtool-0.9 wx-1.5 xmerl-1.3.8 : OTP-18.1.3 : ssh-4.1.2 # asn1-4.0 common_test-1.11 compiler-6.0.1 cosEvent-2.2 cosEventDomain-1.2 cosFileTransfer-1.2 cosNotification-1.2 cosProperty-1.2 cosTime-1.2 cosTransactions-1.3 crypto-3.6.1 debugger-4.1.1 dialyzer-2.8.1 diameter-1.11 edoc-0.7.17 eldap-1.2 erl_docgen-0.4 erl_interface-3.8 erts-7.1 et-1.5.1 eunit-2.2.11 gs-1.6 hipe-3.13 ic-4.4 inets-6.0.2 jinterface-1.6 kernel-4.1 megaco-3.18 mnesia-4.13.2 observer-2.1 odbc-2.11.1 orber-3.8 os_mon-2.4 ose-1.1 otp_mibs-1.1 parsetools-2.1 percept-0.8.11 public_key-1.0.1 reltool-0.7 runtime_tools-1.9.1 sasl-2.6 snmp-5.2 ssl-7.1 stdlib-2.6 syntax_tools-1.7 test_server-3.9 tools-2.8.1 typer-0.9.9 webtool-0.9 wx-1.5 xmerl-1.3.8 : OTP-18.1.2 : ssh-4.1.1 # asn1-4.0 common_test-1.11 compiler-6.0.1 cosEvent-2.2 cosEventDomain-1.2 cosFileTransfer-1.2 cosNotification-1.2 cosProperty-1.2 cosTime-1.2 cosTransactions-1.3 crypto-3.6.1 debugger-4.1.1 dialyzer-2.8.1 diameter-1.11 edoc-0.7.17 eldap-1.2 erl_docgen-0.4 erl_interface-3.8 erts-7.1 et-1.5.1 eunit-2.2.11 gs-1.6 hipe-3.13 ic-4.4 inets-6.0.2 jinterface-1.6 kernel-4.1 megaco-3.18 mnesia-4.13.2 observer-2.1 odbc-2.11.1 orber-3.8 os_mon-2.4 ose-1.1 otp_mibs-1.1 parsetools-2.1 percept-0.8.11 public_key-1.0.1 reltool-0.7 runtime_tools-1.9.1 sasl-2.6 snmp-5.2 ssl-7.1 stdlib-2.6 syntax_tools-1.7 test_server-3.9 tools-2.8.1 typer-0.9.9 webtool-0.9 wx-1.5 xmerl-1.3.8 : @@ -7,6 +8,8 @@ OTP-18.0.3 : erts-7.0.3 # asn1-4.0 common_test-1.11 compiler-6.0 cosEvent-2.2 co OTP-18.0.2 : erts-7.0.2 runtime_tools-1.9.1 # asn1-4.0 common_test-1.11 compiler-6.0 cosEvent-2.2 cosEventDomain-1.2 cosFileTransfer-1.2 cosNotification-1.2 cosProperty-1.2 cosTime-1.2 cosTransactions-1.3 crypto-3.6 debugger-4.1 dialyzer-2.8 diameter-1.10 edoc-0.7.17 eldap-1.2 erl_docgen-0.4 erl_interface-3.8 et-1.5.1 eunit-2.2.10 gs-1.6 hipe-3.12 ic-4.4 inets-6.0 jinterface-1.6 kernel-4.0 megaco-3.18 mnesia-4.13 observer-2.1 odbc-2.11 orber-3.8 os_mon-2.4 ose-1.1 otp_mibs-1.1 parsetools-2.1 percept-0.8.11 public_key-1.0 reltool-0.7 sasl-2.5 snmp-5.2 ssh-4.0 ssl-7.0 stdlib-2.5 syntax_tools-1.7 test_server-3.9 tools-2.8 typer-0.9.9 webtool-0.9 wx-1.4 xmerl-1.3.8 : OTP-18.0.1 : erts-7.0.1 # asn1-4.0 common_test-1.11 compiler-6.0 cosEvent-2.2 cosEventDomain-1.2 cosFileTransfer-1.2 cosNotification-1.2 cosProperty-1.2 cosTime-1.2 cosTransactions-1.3 crypto-3.6 debugger-4.1 dialyzer-2.8 diameter-1.10 edoc-0.7.17 eldap-1.2 erl_docgen-0.4 erl_interface-3.8 et-1.5.1 eunit-2.2.10 gs-1.6 hipe-3.12 ic-4.4 inets-6.0 jinterface-1.6 kernel-4.0 megaco-3.18 mnesia-4.13 observer-2.1 odbc-2.11 orber-3.8 os_mon-2.4 ose-1.1 otp_mibs-1.1 parsetools-2.1 percept-0.8.11 public_key-1.0 reltool-0.7 runtime_tools-1.9 sasl-2.5 snmp-5.2 ssh-4.0 ssl-7.0 stdlib-2.5 syntax_tools-1.7 test_server-3.9 tools-2.8 typer-0.9.9 webtool-0.9 wx-1.4 xmerl-1.3.8 : OTP-18.0 : asn1-4.0 common_test-1.11 compiler-6.0 cosEvent-2.2 cosEventDomain-1.2 cosFileTransfer-1.2 cosNotification-1.2 cosProperty-1.2 cosTime-1.2 cosTransactions-1.3 crypto-3.6 debugger-4.1 dialyzer-2.8 diameter-1.10 edoc-0.7.17 eldap-1.2 erl_docgen-0.4 erl_interface-3.8 erts-7.0 et-1.5.1 eunit-2.2.10 gs-1.6 hipe-3.12 ic-4.4 inets-6.0 jinterface-1.6 kernel-4.0 megaco-3.18 mnesia-4.13 observer-2.1 odbc-2.11 orber-3.8 os_mon-2.4 ose-1.1 otp_mibs-1.1 parsetools-2.1 percept-0.8.11 public_key-1.0 reltool-0.7 runtime_tools-1.9 sasl-2.5 snmp-5.2 ssh-4.0 ssl-7.0 stdlib-2.5 syntax_tools-1.7 test_server-3.9 tools-2.8 typer-0.9.9 webtool-0.9 wx-1.4 xmerl-1.3.8 # : +OTP-17.5.6.6 : erts-6.4.1.5 # asn1-3.0.4 common_test-1.10.1 compiler-5.0.4 cosEvent-2.1.15 cosEventDomain-1.1.14 cosFileTransfer-1.1.16 cosNotification-1.1.21 cosProperty-1.1.17 cosTime-1.1.14 cosTransactions-1.2.14 crypto-3.5 debugger-4.0.3.1 dialyzer-2.7.4 diameter-1.9.2.1 edoc-0.7.16 eldap-1.1.1 erl_docgen-0.3.7 erl_interface-3.7.20 et-1.5 eunit-2.2.9 gs-1.5.16 hipe-3.11.3 ic-4.3.6 inets-5.10.9 jinterface-1.5.12 kernel-3.2.0.1 megaco-3.17.3 mnesia-4.12.5 observer-2.0.4 odbc-2.10.22 orber-3.7.1 os_mon-2.3.1 ose-1.0.2 otp_mibs-1.0.10 parsetools-2.0.12 percept-0.8.10 public_key-0.23 reltool-0.6.6 runtime_tools-1.8.16.1 sasl-2.4.1 snmp-5.1.2 ssh-3.2.4 ssl-6.0.1.1 stdlib-2.4 syntax_tools-1.6.18 test_server-3.8.1 tools-2.7.2 typer-0.9.8 webtool-0.8.10 wx-1.3.3 xmerl-1.3.7 : +OTP-17.5.6.5 : erts-6.4.1.4 kernel-3.2.0.1 ssl-6.0.1.1 # asn1-3.0.4 common_test-1.10.1 compiler-5.0.4 cosEvent-2.1.15 cosEventDomain-1.1.14 cosFileTransfer-1.1.16 cosNotification-1.1.21 cosProperty-1.1.17 cosTime-1.1.14 cosTransactions-1.2.14 crypto-3.5 debugger-4.0.3.1 dialyzer-2.7.4 diameter-1.9.2.1 edoc-0.7.16 eldap-1.1.1 erl_docgen-0.3.7 erl_interface-3.7.20 et-1.5 eunit-2.2.9 gs-1.5.16 hipe-3.11.3 ic-4.3.6 inets-5.10.9 jinterface-1.5.12 megaco-3.17.3 mnesia-4.12.5 observer-2.0.4 odbc-2.10.22 orber-3.7.1 os_mon-2.3.1 ose-1.0.2 otp_mibs-1.0.10 parsetools-2.0.12 percept-0.8.10 public_key-0.23 reltool-0.6.6 runtime_tools-1.8.16.1 sasl-2.4.1 snmp-5.1.2 ssh-3.2.4 stdlib-2.4 syntax_tools-1.6.18 test_server-3.8.1 tools-2.7.2 typer-0.9.8 webtool-0.8.10 wx-1.3.3 xmerl-1.3.7 : OTP-17.5.6.4 : debugger-4.0.3.1 erts-6.4.1.3 # asn1-3.0.4 common_test-1.10.1 compiler-5.0.4 cosEvent-2.1.15 cosEventDomain-1.1.14 cosFileTransfer-1.1.16 cosNotification-1.1.21 cosProperty-1.1.17 cosTime-1.1.14 cosTransactions-1.2.14 crypto-3.5 dialyzer-2.7.4 diameter-1.9.2.1 edoc-0.7.16 eldap-1.1.1 erl_docgen-0.3.7 erl_interface-3.7.20 et-1.5 eunit-2.2.9 gs-1.5.16 hipe-3.11.3 ic-4.3.6 inets-5.10.9 jinterface-1.5.12 kernel-3.2 megaco-3.17.3 mnesia-4.12.5 observer-2.0.4 odbc-2.10.22 orber-3.7.1 os_mon-2.3.1 ose-1.0.2 otp_mibs-1.0.10 parsetools-2.0.12 percept-0.8.10 public_key-0.23 reltool-0.6.6 runtime_tools-1.8.16.1 sasl-2.4.1 snmp-5.1.2 ssh-3.2.4 ssl-6.0.1 stdlib-2.4 syntax_tools-1.6.18 test_server-3.8.1 tools-2.7.2 typer-0.9.8 webtool-0.8.10 wx-1.3.3 xmerl-1.3.7 : OTP-17.5.6.3 : diameter-1.9.2.1 # asn1-3.0.4 common_test-1.10.1 compiler-5.0.4 cosEvent-2.1.15 cosEventDomain-1.1.14 cosFileTransfer-1.1.16 cosNotification-1.1.21 cosProperty-1.1.17 cosTime-1.1.14 cosTransactions-1.2.14 crypto-3.5 debugger-4.0.3 dialyzer-2.7.4 edoc-0.7.16 eldap-1.1.1 erl_docgen-0.3.7 erl_interface-3.7.20 erts-6.4.1.2 et-1.5 eunit-2.2.9 gs-1.5.16 hipe-3.11.3 ic-4.3.6 inets-5.10.9 jinterface-1.5.12 kernel-3.2 megaco-3.17.3 mnesia-4.12.5 observer-2.0.4 odbc-2.10.22 orber-3.7.1 os_mon-2.3.1 ose-1.0.2 otp_mibs-1.0.10 parsetools-2.0.12 percept-0.8.10 public_key-0.23 reltool-0.6.6 runtime_tools-1.8.16.1 sasl-2.4.1 snmp-5.1.2 ssh-3.2.4 ssl-6.0.1 stdlib-2.4 syntax_tools-1.6.18 test_server-3.8.1 tools-2.7.2 typer-0.9.8 webtool-0.8.10 wx-1.3.3 xmerl-1.3.7 : OTP-17.5.6.2 : erts-6.4.1.2 runtime_tools-1.8.16.1 # asn1-3.0.4 common_test-1.10.1 compiler-5.0.4 cosEvent-2.1.15 cosEventDomain-1.1.14 cosFileTransfer-1.1.16 cosNotification-1.1.21 cosProperty-1.1.17 cosTime-1.1.14 cosTransactions-1.2.14 crypto-3.5 debugger-4.0.3 dialyzer-2.7.4 diameter-1.9.2 edoc-0.7.16 eldap-1.1.1 erl_docgen-0.3.7 erl_interface-3.7.20 et-1.5 eunit-2.2.9 gs-1.5.16 hipe-3.11.3 ic-4.3.6 inets-5.10.9 jinterface-1.5.12 kernel-3.2 megaco-3.17.3 mnesia-4.12.5 observer-2.0.4 odbc-2.10.22 orber-3.7.1 os_mon-2.3.1 ose-1.0.2 otp_mibs-1.0.10 parsetools-2.0.12 percept-0.8.10 public_key-0.23 reltool-0.6.6 sasl-2.4.1 snmp-5.1.2 ssh-3.2.4 ssl-6.0.1 stdlib-2.4 syntax_tools-1.6.18 test_server-3.8.1 tools-2.7.2 typer-0.9.8 webtool-0.8.10 wx-1.3.3 xmerl-1.3.7 : diff --git a/system/doc/reference_manual/typespec.xml b/system/doc/reference_manual/typespec.xml index 7891f3a6b9..22627058c1 100644 --- a/system/doc/reference_manual/typespec.xml +++ b/system/doc/reference_manual/typespec.xml @@ -197,6 +197,9 @@ <cell><c>char()</c></cell><cell><c>0..16#10ffff</c></cell> </row> <row> + <cell><c>nil()</c></cell><cell><c>[]</c></cell> + </row> + <row> <cell><c>number()</c></cell><cell><c>integer() | float()</c></cell> </row> <row> @@ -312,7 +315,7 @@ <p> As seen, the basic syntax of a type is an atom followed by closed parentheses. New types are declared using <c>-type</c> and <c>-opaque</c> - compiler attributes as in the following: + attributes as in the following: </p> <pre> -type my_struct_type() :: Type. @@ -435,8 +438,8 @@ <section> <title>Specifications for Functions</title> <p> - A specification (or contract) for a function is given using the new - compiler attribute <c>-spec</c>. The general format is as follows: + A specification (or contract) for a function is given using the + <c>-spec</c> attribute. The general format is as follows: </p> <pre> -spec Module:Function(ArgType1, ..., ArgTypeN) -> ReturnType.</pre> @@ -451,7 +454,7 @@ explicitly) import these functions. </p> <p> - Within a given module, the following shorthand suffice in most cases: + Within a given module, the following shorthand suffices in most cases: </p> <pre> -spec Function(ArgType1, ..., ArgTypeN) -> ReturnType.</pre> |